From 143d5d779c3719e8e85287fb2bc32a24ff9818bb Mon Sep 17 00:00:00 2001 From: SDL Wiki Bot Date: Fri, 14 Jun 2024 06:11:54 +0000 Subject: [PATCH] Sync SDL2 wiki -> header --- include/SDL.h | 2 +- include/SDL_assert.h | 10 +- include/SDL_atomic.h | 34 +-- include/SDL_audio.h | 123 +++++------ include/SDL_bits.h | 2 +- include/SDL_blendmode.h | 12 +- include/SDL_clipboard.h | 4 +- include/SDL_endian.h | 8 +- include/SDL_error.h | 8 +- include/SDL_events.h | 60 +++--- include/SDL_filesystem.h | 4 +- include/SDL_gamecontroller.h | 166 +++++++-------- include/SDL_gesture.h | 12 +- include/SDL_guid.h | 8 +- include/SDL_haptic.h | 79 +++---- include/SDL_hidapi.h | 4 +- include/SDL_hints.h | 38 ++-- include/SDL_joystick.h | 163 ++++++++------- include/SDL_keyboard.h | 20 +- include/SDL_loadso.h | 8 +- include/SDL_log.h | 81 +++---- include/SDL_main.h | 16 +- include/SDL_messagebox.h | 13 +- include/SDL_metal.h | 6 +- include/SDL_mouse.h | 46 ++-- include/SDL_mutex.h | 38 ++-- include/SDL_pixels.h | 94 ++++----- include/SDL_power.h | 4 +- include/SDL_rect.h | 68 +++--- include/SDL_render.h | 395 ++++++++++++++++++----------------- include/SDL_rwops.h | 96 ++++----- include/SDL_sensor.h | 36 ++-- include/SDL_surface.h | 200 +++++++++--------- include/SDL_system.h | 40 ++-- include/SDL_syswm.h | 4 +- include/SDL_thread.h | 32 +-- include/SDL_timer.h | 10 +- include/SDL_touch.h | 8 +- include/SDL_version.h | 2 +- include/SDL_video.h | 314 ++++++++++++++-------------- include/SDL_vulkan.h | 20 +- 41 files changed, 1150 insertions(+), 1138 deletions(-) diff --git a/include/SDL.h b/include/SDL.h index c3eecbc54c..87149a55f6 100644 --- a/include/SDL.h +++ b/include/SDL.h @@ -131,7 +131,7 @@ extern "C" { * 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/SDL_assert.h b/include/SDL_assert.h index a6a048efce..894a3798e3 100644 --- a/include/SDL_assert.h +++ b/include/SDL_assert.h @@ -193,8 +193,8 @@ extern 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. */ typedef SDL_AssertState (SDLCALL *SDL_AssertionHandler)( @@ -214,8 +214,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 2.0.0. * @@ -256,7 +256,7 @@ extern DECLSPEC SDL_AssertionHandler SDLCALL SDL_GetDefaultAssertionHandler(void * 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 2.0.2. diff --git a/include/SDL_atomic.h b/include/SDL_atomic.h index d8cb3c0daf..5469802204 100644 --- a/include/SDL_atomic.h +++ b/include/SDL_atomic.h @@ -85,7 +85,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. * @@ -102,7 +102,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicTryLock(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 2.0.0. * @@ -119,7 +119,7 @@ extern DECLSPEC void SDLCALL SDL_AtomicLock(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 2.0.0. * @@ -262,9 +262,9 @@ typedef struct SDL_atomic_t { * ***Note: If you don't know what this function is for, you shouldn't use * it!*** * - * \param a a pointer to an SDL_atomic_t variable to be modified - * \param oldval the old value - * \param newval the new value + * \param a a pointer to an SDL_atomic_t variable to be modified. + * \param oldval the old value. + * \param newval the new value. * \returns SDL_TRUE if the atomic variable was set, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.0. @@ -283,8 +283,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCAS(SDL_atomic_t *a, int oldval, int * ***Note: If you don't know what this function is for, you shouldn't use * it!*** * - * \param a a pointer to an SDL_atomic_t variable to be modified - * \param v the desired value + * \param a a pointer to an SDL_atomic_t variable to be modified. + * \param v the desired value. * \returns the previous value of the atomic variable. * * \since This function is available since SDL 2.0.2. @@ -299,7 +299,7 @@ extern DECLSPEC int SDLCALL SDL_AtomicSet(SDL_atomic_t *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_atomic_t variable + * \param a a pointer to an SDL_atomic_t variable. * \returns the current value of an atomic variable. * * \since This function is available since SDL 2.0.2. @@ -316,8 +316,8 @@ extern DECLSPEC int SDLCALL SDL_AtomicGet(SDL_atomic_t *a); * ***Note: If you don't know what this function is for, you shouldn't use * it!*** * - * \param a a pointer to an SDL_atomic_t variable to be modified - * \param v the desired value to add + * \param a a pointer to an SDL_atomic_t variable to be modified. + * \param v the desired value to add. * \returns the previous value of the atomic variable. * * \since This function is available since SDL 2.0.2. @@ -350,9 +350,9 @@ extern DECLSPEC int SDLCALL SDL_AtomicAdd(SDL_atomic_t *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. * * \since This function is available since SDL 2.0.0. @@ -369,8 +369,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AtomicCASPtr(void **a, void *oldval, void * * ***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. * * \since This function is available since SDL 2.0.2. @@ -386,7 +386,7 @@ extern 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. * * \since This function is available since SDL 2.0.2. diff --git a/include/SDL_audio.h b/include/SDL_audio.h index 936b78aa64..8f874dcc68 100644 --- a/include/SDL_audio.h +++ b/include/SDL_audio.h @@ -152,7 +152,7 @@ typedef Uint16 SDL_AudioFormat; * This function is called when the audio device needs more data. * * \param userdata An application-specific parameter saved in the - * SDL_AudioSpec structure + * SDL_AudioSpec structure. * \param stream A pointer to the audio data buffer. * \param len Length of **stream** in bytes. */ @@ -284,7 +284,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDrivers(void); * meant to be proper names. * * \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. * @@ -311,7 +311,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDriver(int index); * specific need to designate the audio driver you want to use. You should * normally use SDL_Init() or SDL_InitSubSystem(). * - * \param driver_name the name of the desired audio driver + * \param driver_name the name of the desired audio driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -449,7 +449,7 @@ typedef Uint32 SDL_AudioDeviceID; * ``` * * \param iscapture zero to request playback devices, non-zero to request - * recording devices + * recording devices. * \returns the number of available devices exposed by the current driver or * -1 if an explicit list of devices can't be determined. A return * value of -1 does not necessarily mean an error condition. @@ -475,7 +475,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumAudioDevices(int iscapture); * invalid next time any of several other SDL functions are called. * * \param index the index of the audio device; valid values range from 0 to - * SDL_GetNumAudioDevices() - 1 + * SDL_GetNumAudioDevices() - 1. * \param iscapture non-zero to query the list of recording devices, zero to * query the list of output devices. * \returns the name of the audio device at the requested index, or NULL on @@ -501,11 +501,11 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index, * count. * * \param index the index of the audio device; valid values range from 0 to - * SDL_GetNumAudioDevices() - 1 + * SDL_GetNumAudioDevices() - 1. * \param iscapture non-zero to query the list of recording devices, zero to * query the list of output devices. * \param spec The SDL_AudioSpec to be initialized by this function. - * \returns 0 on success, nonzero on error + * \returns 0 on success, nonzero on error. * * \since This function is available since SDL 2.0.16. * @@ -539,7 +539,7 @@ extern DECLSPEC int SDLCALL SDL_GetAudioDeviceSpec(int index, * \param spec The SDL_AudioSpec to be initialized by this function. * \param iscapture non-zero to query the default recording device, zero to * query the default output device. - * \returns 0 on success, nonzero on error + * \returns 0 on success, nonzero on error. * * \since This function is available since SDL 2.24.0. * @@ -642,12 +642,12 @@ extern DECLSPEC int SDLCALL SDL_GetDefaultAudioInfo(char **name, * driver-specific name as appropriate. NULL requests the most * reasonable default device. * \param iscapture non-zero to specify a device should be opened for - * recording, not playback + * recording, not playback. * \param desired an SDL_AudioSpec structure representing the desired output - * format; see SDL_OpenAudio() for more information + * format; see SDL_OpenAudio() for more information. * \param obtained an SDL_AudioSpec structure filled in with the actual output - * format; see SDL_OpenAudio() for more information - * \param allowed_changes 0, or one or more flags OR'd together + * format; see SDL_OpenAudio() for more information. + * \param allowed_changes 0, or one or more flags OR'd together. * \returns a valid device ID that is > 0 on success or 0 on failure; call * SDL_GetError() for more information. * @@ -709,7 +709,7 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioStatus(void); * Use this function to get the current audio state of an audio device. * * \param dev the ID of an audio device previously opened with - * SDL_OpenAudioDevice() + * SDL_OpenAudioDevice(). * \returns the SDL_AudioStatus of the specified audio device. * * \since This function is available since SDL 2.0.0. @@ -742,7 +742,7 @@ extern DECLSPEC SDL_AudioStatus SDLCALL SDL_GetAudioDeviceStatus(SDL_AudioDevice * * ...and is only useful if you used the legacy SDL_OpenAudio() function. * - * \param pause_on non-zero to pause, 0 to unpause + * \param pause_on non-zero to pause, 0 to unpause. * * \since This function is available since SDL 2.0.0. * @@ -772,8 +772,8 @@ extern DECLSPEC void SDLCALL SDL_PauseAudio(int pause_on); * callback, you shouldn't pause the audio device, as it will lead to dropouts * in the audio playback. Instead, you should use SDL_LockAudioDevice(). * - * \param dev a device opened by SDL_OpenAudioDevice() - * \param pause_on non-zero to pause, 0 to unpause + * \param dev a device opened by SDL_OpenAudioDevice(). + * \param pause_on non-zero to pause, 0 to unpause. * * \since This function is available since SDL 2.0.0. * @@ -838,14 +838,14 @@ extern DECLSPEC void SDLCALL SDL_PauseAudioDevice(SDL_AudioDeviceID dev, * SDL_LoadWAV("sample.wav", &spec, &buf, &len); * ``` * - * \param src The data source for the WAVE data - * \param freesrc If non-zero, SDL will _always_ free the data source + * \param src The data source for the WAVE data. + * \param freesrc If non-zero, SDL will _always_ free the data source. * \param spec An SDL_AudioSpec that will be filled in with the wave file's - * format details + * format details. * \param audio_buf A pointer filled with the audio data, allocated by the * function. * \param audio_len A pointer filled with the length of the audio data buffer - * in bytes + * in bytes. * \returns This function, if successfully called, returns `spec`, which will * be filled with the audio data format of the wave source data. * `audio_buf` will be filled with a pointer to an allocated buffer @@ -886,7 +886,7 @@ extern DECLSPEC SDL_AudioSpec *SDLCALL SDL_LoadWAV_RW(SDL_RWops * src, * this function with a NULL pointer. * * \param audio_buf a pointer to the buffer created by SDL_LoadWAV() or - * SDL_LoadWAV_RW() + * SDL_LoadWAV_RW(). * * \since This function is available since SDL 2.0.0. * @@ -910,15 +910,16 @@ extern DECLSPEC void SDLCALL SDL_FreeWAV(Uint8 * audio_buf); * and then can call SDL_ConvertAudio() to complete the conversion. * * \param cvt an SDL_AudioCVT structure filled in with audio conversion - * information + * information. * \param src_format the source format of the audio data; for more info see - * SDL_AudioFormat - * \param src_channels the number of channels in the source - * \param src_rate the frequency (sample-frames-per-second) of the source + * SDL_AudioFormat. + * \param src_channels the number of channels in the source. + * \param src_rate the frequency (sample-frames-per-second) of the source. * \param dst_format the destination format of the audio data; for more info - * see SDL_AudioFormat - * \param dst_channels the number of channels in the destination - * \param dst_rate the frequency (sample-frames-per-second) of the destination + * see SDL_AudioFormat. + * \param dst_channels the number of channels in the destination. + * \param dst_rate the frequency (sample-frames-per-second) of the + * destination. * \returns 1 if the audio filter is prepared, 0 if no conversion is needed, * or a negative error code on failure; call SDL_GetError() for more * information. @@ -989,12 +990,12 @@ typedef struct _SDL_AudioStream SDL_AudioStream; /** * Create a new audio stream. * - * \param src_format The format of the source audio - * \param src_channels The number of channels of the source audio - * \param src_rate The sampling rate of the source audio - * \param dst_format The format of the desired audio output - * \param dst_channels The number of channels of the desired audio output - * \param dst_rate The sampling rate of the desired audio output + * \param src_format The format of the source audio. + * \param src_channels The number of channels of the source audio. + * \param src_rate The sampling rate of the source audio. + * \param dst_format The format of the desired audio output. + * \param dst_channels The number of channels of the desired audio output. + * \param dst_rate The sampling rate of the desired audio output. * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.7. @@ -1016,9 +1017,9 @@ extern DECLSPEC SDL_AudioStream * SDLCALL SDL_NewAudioStream(const SDL_AudioForm /** * Add data to be converted/resampled to the stream. * - * \param stream The stream the audio data is being added to - * \param buf A pointer to the audio data to add - * \param len The number of bytes to write to the stream + * \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 -1 on error. * * \since This function is available since SDL 2.0.7. @@ -1035,10 +1036,10 @@ extern DECLSPEC int SDLCALL SDL_AudioStreamPut(SDL_AudioStream *stream, const vo /** * Get converted/resampled data from the stream * - * \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. * * \since This function is available since SDL 2.0.7. * @@ -1133,11 +1134,11 @@ extern DECLSPEC void SDLCALL SDL_FreeAudioStream(SDL_AudioStream *stream); * ...where `format` is the obtained format of the audio device from the * legacy SDL_OpenAudio() function. * - * \param dst the destination for the mixed audio - * \param src the source audio buffer to be mixed - * \param len the length of the audio buffer in bytes + * \param dst the destination for the mixed audio. + * \param src the source audio buffer to be mixed. + * \param len the length of the audio buffer in bytes. * \param volume ranges from 0 - 128, and should be set to SDL_MIX_MAXVOLUME - * for full audio volume + * for full audio volume. * * \since This function is available since SDL 2.0.0. * @@ -1166,14 +1167,14 @@ extern DECLSPEC void SDLCALL SDL_MixAudio(Uint8 * dst, const Uint8 * src, * SDL_MixAudioFormat() is really only needed when you're mixing a single * audio stream with a volume adjustment. * - * \param dst the destination for the mixed audio - * \param src the source audio buffer to be mixed + * \param 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 -128 - ∞ (at -128, the volume is at 0%, at 0 - * 100% and the higher the number, the bigger the %), and should - * be set to SDL_MIX_MAXVOLUME for full audio volume + * be set to SDL_MIX_MAXVOLUME for full audio volume. * * \since This function is available since SDL 2.0.0. */ @@ -1217,9 +1218,9 @@ extern DECLSPEC void SDLCALL SDL_MixAudioFormat(Uint8 * dst, * from planar audio formats into a non-planar one (see SDL_AudioFormat) * before queuing audio. * - * \param dev the device ID to which we will queue audio - * \param data the data to queue to the device for later playback - * \param len the number of bytes (not samples!) to which `data` points + * \param dev the device ID to which we will queue audio. + * \param data the data to queue to the device for later playback. + * \param len the number of bytes (not samples!) to which `data` points. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1265,9 +1266,9 @@ extern DECLSPEC int SDLCALL SDL_QueueAudio(SDL_AudioDeviceID dev, const void *da * You should not call SDL_LockAudio() on the device before dequeueing; SDL * handles locking internally for this function. * - * \param dev the device ID from which we will dequeue audio - * \param data a pointer into where audio data should be copied - * \param len the number of bytes (not samples!) to which (data) points + * \param dev the device ID from which we will dequeue audio. + * \param data a pointer into where audio data should be copied. + * \param len the number of bytes (not samples!) to which (data) points. * \returns the number of bytes dequeued, which could be less than requested; * call SDL_GetError() for more information. * @@ -1301,7 +1302,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_DequeueAudio(SDL_AudioDeviceID dev, void *dat * You should not call SDL_LockAudio() on the device before querying; SDL * handles locking internally for this function. * - * \param dev the device ID of which we will query queued audio size + * \param dev the device ID of which we will query queued audio size. * \returns the number of bytes (not samples!) of queued audio. * * \since This function is available since SDL 2.0.4. @@ -1336,7 +1337,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetQueuedAudioSize(SDL_AudioDeviceID dev); * * This function always succeeds and thus returns void. * - * \param dev the device ID of which to clear the audio queue + * \param dev the device ID of which to clear the audio queue. * * \since This function is available since SDL 2.0.4. * @@ -1408,7 +1409,7 @@ extern DECLSPEC void SDLCALL SDL_LockAudio(void); * at once, not only will you block the audio callback, you'll block the other * thread. * - * \param dev the ID of the device to be locked + * \param dev the ID of the device to be locked. * * \since This function is available since SDL 2.0.0. * @@ -1441,7 +1442,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockAudio(void); * * This function should be paired with a previous SDL_LockAudioDevice() call. * - * \param dev the ID of the device to be unlocked + * \param dev the ID of the device to be unlocked. * * \since This function is available since SDL 2.0.0. * @@ -1483,7 +1484,7 @@ extern DECLSPEC void SDLCALL SDL_CloseAudio(void); * The device ID is invalid as soon as the device is closed, and is eligible * for reuse in a new SDL_OpenAudioDevice() call immediately. * - * \param dev an audio device previously opened with SDL_OpenAudioDevice() + * \param dev an audio device previously opened with SDL_OpenAudioDevice(). * * \since This function is available since SDL 2.0.0. * diff --git a/include/SDL_bits.h b/include/SDL_bits.h index 0b22131c31..03dda34a4e 100644 --- a/include/SDL_bits.h +++ b/include/SDL_bits.h @@ -59,7 +59,7 @@ extern __inline int _SDL_bsr_watcom(Uint32); /** * Use this function to get the index of the most significant (set) bit in a * - * \param x the number to find the MSB of + * \param x the number to find the MSB of. * \returns the index of the most significant bit of x, or -1 if x is 0. */ SDL_FORCE_INLINE int diff --git a/include/SDL_blendmode.h b/include/SDL_blendmode.h index 75d21fe631..7a13585a79 100644 --- a/include/SDL_blendmode.h +++ b/include/SDL_blendmode.h @@ -159,18 +159,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/SDL_clipboard.h b/include/SDL_clipboard.h index 3a02774615..e5623e9eb6 100644 --- a/include/SDL_clipboard.h +++ b/include/SDL_clipboard.h @@ -41,7 +41,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. * @@ -85,7 +85,7 @@ extern 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. * diff --git a/include/SDL_endian.h b/include/SDL_endian.h index 38ae231f78..1be797a6f3 100644 --- a/include/SDL_endian.h +++ b/include/SDL_endian.h @@ -184,7 +184,7 @@ extern __inline Uint16 SDL_Swap16(Uint16); /** * Use this function to swap the byte order of a 16-bit value. * - * \param x the value to be swapped + * \param x the value to be swapped. * \returns the swapped value. * * \sa SDL_SwapBE16 @@ -245,7 +245,7 @@ extern __inline Uint32 SDL_Swap32(Uint32); /** * Use this function to swap the byte order of a 32-bit value. * - * \param x the value to be swapped + * \param x the value to be swapped. * \returns the swapped value. * * \sa SDL_SwapBE32 @@ -300,7 +300,7 @@ extern __inline Uint64 SDL_Swap64(Uint64); /** * Use this function to swap the byte order of a 64-bit value. * - * \param x the value to be swapped + * \param x the value to be swapped. * \returns the swapped value. * * \sa SDL_SwapBE64 @@ -326,7 +326,7 @@ SDL_Swap64(Uint64 x) /** * Use this function to swap the byte order of a floating point value. * - * \param x the value to be swapped + * \param x the value to be swapped. * \returns the swapped value. * * \sa SDL_SwapFloatBE diff --git a/include/SDL_error.h b/include/SDL_error.h index aca98f70c3..69e0bb6e48 100644 --- a/include/SDL_error.h +++ b/include/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 2.0.0. @@ -109,8 +109,8 @@ extern DECLSPEC const char *SDLCALL SDL_GetError(void); * otherwise operates exactly the same as SDL_GetError(). * * \param errstr A buffer to fill with the last error message that was set for - * the current thread - * \param maxlen The size of the buffer pointed to by the errstr parameter + * the current thread. + * \param maxlen The size of the buffer pointed to by the errstr parameter. * \returns the pointer passed in as the `errstr` parameter. * * \since This function is available since SDL 2.0.14. diff --git a/include/SDL_events.h b/include/SDL_events.h index ada011afe4..81fd6e41b6 100644 --- a/include/SDL_events.h +++ b/include/SDL_events.h @@ -746,15 +746,15 @@ typedef enum SDL_eventaction * * This function is thread-safe. * - * \param events destination buffer for the retrieved events + * \param events destination buffer for the retrieved events. * \param numevents if action is SDL_ADDEVENT, the number of events to add * back to the event queue; if action is SDL_PEEKEVENT or - * SDL_GETEVENT, the maximum number of events to retrieve - * \param action action to take; see [[#action|Remarks]] for details + * SDL_GETEVENT, the maximum number of events to retrieve. + * \param action action to take; see [[#action|Remarks]] for details. * \param minType minimum value of the event type to be considered; - * SDL_FIRSTEVENT is a safe choice + * SDL_FIRSTEVENT is a safe choice. * \param maxType maximum value of the event type to be considered; - * SDL_LASTEVENT is a safe choice + * SDL_LASTEVENT is a safe choice. * \returns the number of events actually stored or a negative error code on * failure; call SDL_GetError() for more information. * @@ -775,7 +775,7 @@ extern 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. * @@ -792,9 +792,9 @@ extern 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. * @@ -818,7 +818,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasEvents(Uint32 minType, Uint32 maxType); * sure that all pending OS events are flushed, you can call SDL_PumpEvents() * on the main thread immediately before the flush call. * - * \param type the type of event to be cleared; see SDL_EventType for details + * \param type the type of event to be cleared; see SDL_EventType for details. * * \since This function is available since SDL 2.0.0. * @@ -841,9 +841,9 @@ extern 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 2.0.0. * @@ -884,7 +884,7 @@ extern 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 1 if there is a pending event or 0 if there are none available. * * \since This function is available since SDL 2.0.0. @@ -908,7 +908,7 @@ extern DECLSPEC int 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 1 on success or 0 if there was an error while waiting for events; * call SDL_GetError() for more information. * @@ -931,9 +931,9 @@ extern DECLSPEC int SDLCALL SDL_WaitEvent(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. * \param timeout the maximum number of milliseconds to wait for the next - * available event + * available event. * \returns 1 on success or 0 if there was an error while waiting for events; * call SDL_GetError() for more information. This also returns 0 if * the timeout elapsed without an event arriving. @@ -968,7 +968,7 @@ extern DECLSPEC int SDLCALL SDL_WaitEventTimeout(SDL_Event * event, * 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. @@ -985,8 +985,8 @@ extern DECLSPEC int SDLCALL SDL_PushEvent(SDL_Event * event); * A function pointer used for callbacks that watch the event queue. * * \param userdata what was passed as `userdata` to SDL_SetEventFilter() or - * SDL_AddEventWatch, etc - * \param event the event that triggered the callback + * 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. * @@ -1026,8 +1026,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`. * * \since This function is available since SDL 2.0.0. * @@ -1046,9 +1046,9 @@ extern DECLSPEC void SDLCALL SDL_SetEventFilter(SDL_EventFilter filter, * This function can be used to "chain" filters, by saving the existing filter * before replacing it with a function that will call that saved filter. * - * \param filter the current callback function will be stored here + * \param 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 2.0.0. @@ -1077,7 +1077,7 @@ extern 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`. * * \since This function is available since SDL 2.0.0. * @@ -1093,8 +1093,8 @@ extern DECLSPEC void SDLCALL SDL_AddEventWatch(SDL_EventFilter filter, * 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 2.0.0. * @@ -1111,8 +1111,8 @@ extern DECLSPEC void SDLCALL SDL_DelEventWatch(SDL_EventFilter filter, * 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 2.0.0. * @@ -1138,8 +1138,8 @@ extern DECLSPEC void SDLCALL SDL_FilterEvents(SDL_EventFilter filter, * from the event queue and will not be filtered * - `SDL_ENABLE`: the event will be processed normally * - * \param type the type of event; see SDL_EventType for details - * \param state how to process the event + * \param type the type of event; see SDL_EventType for details. + * \param state how to process the event. * \returns `SDL_DISABLE` or `SDL_ENABLE`, representing the processing state * of the event before this function makes any changes to it. * @@ -1161,7 +1161,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_EventState(Uint32 type, int state); * Note, (Uint32)-1 means the maximum unsigned 32-bit integer value (or * 0xFFFFFFFF), but is clearer to write. * - * \param numevents the number of events to be allocated + * \param numevents the number of events to be allocated. * \returns the beginning event number, or (Uint32)-1 if there are not enough * user-defined events left. * diff --git a/include/SDL_filesystem.h b/include/SDL_filesystem.h index 04e405dba1..1ebdaa84e2 100644 --- a/include/SDL_filesystem.h +++ b/include/SDL_filesystem.h @@ -126,8 +126,8 @@ extern 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.). diff --git a/include/SDL_gamecontroller.h b/include/SDL_gamecontroller.h index ced8dd9ea7..1a653e66c8 100644 --- a/include/SDL_gamecontroller.h +++ b/include/SDL_gamecontroller.h @@ -154,8 +154,8 @@ typedef struct SDL_GameControllerButtonBind * processing it, so take this into consideration if you are in a memory * constrained environment. * - * \param rw the data stream for the mappings to be added - * \param freerw non-zero to close the stream after being read + * \param rw the data stream for the mappings to be added. + * \param freerw non-zero to close the stream after being read. * \returns the number of mappings added or -1 on error; call SDL_GetError() * for more information. * @@ -193,7 +193,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerAddMappingsFromRW(SDL_RWops * rw, * "341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7" * ``` * - * \param mappingString the mapping string + * \param mappingString the mapping string. * \returns 1 if a new mapping is added, 0 if an existing mapping is updated, * -1 on error; call SDL_GetError() for more information. * @@ -228,7 +228,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForIndex(int mapping_ind * * 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. * @@ -247,7 +247,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMappingForGUID(SDL_JoystickGUID * Details about mappings are discussed with SDL_GameControllerAddMapping(). * * \param gamecontroller the game controller you want to get the current - * mapping for + * mapping for. * \returns a string that has the controller's mapping or NULL if no mapping * is available; call SDL_GetError() for more information. * @@ -265,7 +265,7 @@ extern DECLSPEC char * SDLCALL SDL_GameControllerMapping(SDL_GameController *gam * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks() + * SDL_NumJoysticks(). * \returns SDL_TRUE if the given joystick is supported by the game controller * interface, SDL_FALSE if it isn't or it's an invalid index. * @@ -285,7 +285,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsGameController(int joystick_index); * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the implementation-dependent name for the game controller, or NULL * if there is no name or the index is invalid. * @@ -306,7 +306,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerNameForIndex(int joystick_ * SDL_JoystickOpen(). * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the implementation-dependent path for the game controller, or NULL * if there is no path or the index is invalid. * @@ -322,7 +322,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerPathForIndex(int joystick_ * This can be called before any controllers are opened. * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the controller type. * * \since This function is available since SDL 2.0.12. @@ -335,7 +335,7 @@ extern DECLSPEC SDL_GameControllerType SDLCALL SDL_GameControllerTypeForIndex(in * This can be called before any controllers are opened. * * \param joystick_index the device_index of a device, from zero to - * SDL_NumJoysticks()-1 + * SDL_NumJoysticks()-1. * \returns the mapping string. Must be freed with SDL_free(). Returns NULL if * no mapping is available. * @@ -355,7 +355,7 @@ extern DECLSPEC char *SDLCALL SDL_GameControllerMappingForDeviceIndex(int joysti * be used there instead. * * \param joystick_index the device_index of a device, up to - * SDL_NumJoysticks() + * SDL_NumJoysticks(). * \returns a gamecontroller identifier or NULL if an error occurred; call * SDL_GetError() for more information. * @@ -370,7 +370,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerOpen(int joystick_ /** * Get the SDL_GameController associated with an instance id. * - * \param joyid the instance id to get the SDL_GameController for + * \param joyid the instance id to get the SDL_GameController for. * \returns an SDL_GameController on success or NULL on failure; call * SDL_GetError() for more information. * @@ -402,7 +402,7 @@ extern DECLSPEC SDL_GameController *SDLCALL SDL_GameControllerFromPlayerIndex(in * it takes a controller identifier instead of the (unstable) device index. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns the implementation dependent name for the game controller, or NULL * if there is no name or the identifier passed is invalid. * @@ -420,7 +420,7 @@ extern DECLSPEC const char *SDLCALL SDL_GameControllerName(SDL_GameController *g * it takes a controller identifier instead of the (unstable) device index. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns the implementation dependent path for the game controller, or NULL * if there is no path or the identifier passed is invalid. * @@ -545,7 +545,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_GameControllerGetSteamHandle(SDL_GameControll * Check if a controller has been opened and is currently connected. * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * \returns SDL_TRUE if the controller has been opened and is currently * connected, or SDL_FALSE if not. * @@ -570,7 +570,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerGetAttached(SDL_GameControlle * cause SDL to crash. * * \param gamecontroller the game controller object that you want to get a - * joystick from + * joystick from. * \returns a SDL_Joystick object; call SDL_GetError() for more information. * * \since This function is available since SDL 2.0.0. @@ -587,7 +587,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_GameControllerGetJoystick(SDL_GameCont * Any number can be passed to SDL_GameControllerEventState(), but only -1, 0, * and 1 will have any effect. Other numbers will just be returned. * - * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE` + * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`. * \returns the same value passed to the function, with exception to -1 * (SDL_QUERY), which will return the current state. * @@ -646,7 +646,7 @@ typedef enum SDL_GameControllerAxis * `SDL_CONTROLLER_AXIS_TRIGGERRIGHT` and `SDL_CONTROLLER_AXIS_TRIGGERLEFT`, * respectively. * - * \param str string representing a SDL_GameController axis + * \param str string representing a SDL_GameController axis. * \returns the SDL_GameControllerAxis enum corresponding to the input string, * or `SDL_CONTROLLER_AXIS_INVALID` if no match was found. * @@ -661,7 +661,7 @@ extern DECLSPEC SDL_GameControllerAxis SDLCALL SDL_GameControllerGetAxisFromStri * * The caller should not SDL_free() the returned string. * - * \param axis an enum value for a given SDL_GameControllerAxis + * \param axis an enum value for a given SDL_GameControllerAxis. * \returns a string for the given axis, or NULL if an invalid axis is * specified. The string returned is of the format used by * SDL_GameController mapping strings. @@ -675,8 +675,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForAxis(SDL_GameC /** * Get the SDL joystick layer binding for a controller axis mapping. * - * \param gamecontroller a game controller - * \param axis an axis enum value (one of the SDL_GameControllerAxis values) + * \param gamecontroller a game controller. + * \param axis an axis enum value (one of the SDL_GameControllerAxis values). * \returns a SDL_GameControllerButtonBind describing the bind. On failure * (like the given Controller axis doesn't exist on the device), its * `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`. @@ -695,8 +695,8 @@ SDL_GameControllerGetBindForAxis(SDL_GameController *gamecontroller, * This merely reports whether the controller's mapping defined this axis, as * that is all the information SDL has about the physical device. * - * \param gamecontroller a game controller - * \param axis an axis enum value (an SDL_GameControllerAxis value) + * \param gamecontroller a game controller. + * \param axis an axis enum value (an SDL_GameControllerAxis value). * \returns SDL_TRUE if the controller has this axis, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -716,8 +716,8 @@ SDL_GameControllerHasAxis(SDL_GameController *gamecontroller, SDL_GameController * 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 gamecontroller a game controller - * \param axis an axis index (one of the SDL_GameControllerAxis values) + * \param gamecontroller a game controller. + * \param axis an axis index (one of the SDL_GameControllerAxis values). * \returns axis state (including 0) on success or 0 (also) on failure; call * SDL_GetError() for more information. * @@ -766,7 +766,7 @@ typedef enum SDL_GameControllerButton * SDL_GameController mapping. You do not normally need to call this function * unless you are parsing SDL_GameController mappings in your own code. * - * \param str string representing a SDL_GameController axis + * \param str string representing a SDL_GameController axis. * \returns the SDL_GameControllerButton enum corresponding to the input * string, or `SDL_CONTROLLER_AXIS_INVALID` if no match was found. * @@ -779,7 +779,7 @@ extern DECLSPEC SDL_GameControllerButton SDLCALL SDL_GameControllerGetButtonFrom * * The caller should not SDL_free() the returned string. * - * \param button an enum value for a given SDL_GameControllerButton + * \param button an enum value for a given SDL_GameControllerButton. * \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_GameController mapping strings. @@ -793,8 +793,8 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetStringForButton(SDL_Gam /** * Get the SDL joystick layer binding for a controller button mapping. * - * \param gamecontroller a game controller - * \param button an button enum value (an SDL_GameControllerButton value) + * \param gamecontroller a game controller. + * \param button an button enum value (an SDL_GameControllerButton value). * \returns a SDL_GameControllerButtonBind describing the bind. On failure * (like the given Controller button doesn't exist on the device), * its `.bindType` will be `SDL_CONTROLLER_BINDTYPE_NONE`. @@ -813,8 +813,8 @@ SDL_GameControllerGetBindForButton(SDL_GameController *gamecontroller, * This merely reports whether the controller's mapping defined this button, * as that is all the information SDL has about the physical device. * - * \param gamecontroller a game controller - * \param button a button enum value (an SDL_GameControllerButton value) + * \param gamecontroller a game controller. + * \param button a button enum value (an SDL_GameControllerButton value). * \returns SDL_TRUE if the controller has this button, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -825,8 +825,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasButton(SDL_GameController /** * Get the current state of a button on a game controller. * - * \param gamecontroller a game controller - * \param button a button index (one of the SDL_GameControllerButton values) + * \param gamecontroller a game controller. + * \param button a button index (one of the SDL_GameControllerButton values). * \returns 1 for pressed state or 0 for not pressed state or error; call * SDL_GetError() for more information. * @@ -862,8 +862,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetTouchpadFinger(SDL_GameControll /** * Return whether a game controller has a particular sensor. * - * \param gamecontroller The controller to query - * \param type The type of sensor to query + * \param gamecontroller The controller to query. + * \param type The type of sensor to query. * \returns SDL_TRUE if the sensor exists, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -873,9 +873,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasSensor(SDL_GameController /** * Set whether data reporting for a game controller sensor is enabled. * - * \param gamecontroller The controller to update - * \param type The type of sensor to enable/disable - * \param enabled Whether data reporting should be enabled + * \param gamecontroller The controller to update. + * \param type The type of sensor to enable/disable. + * \param enabled Whether data reporting should be enabled. * \returns 0 or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -885,8 +885,8 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetSensorEnabled(SDL_GameControlle /** * Query whether sensor data reporting is enabled for a game controller. * - * \param gamecontroller The controller to query - * \param type The type of sensor to query + * \param gamecontroller The controller to query. + * \param type The type of sensor to query. * \returns SDL_TRUE if the sensor is enabled, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -897,8 +897,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerIsSensorEnabled(SDL_GameContr * Get the data rate (number of events per second) of a game controller * sensor. * - * \param gamecontroller The controller to query - * \param type The type of sensor to query + * \param gamecontroller The controller to query. + * \param type The type of sensor to query. * \return the data rate, or 0.0f if the data rate is not available. * * \since This function is available since SDL 2.0.16. @@ -911,10 +911,10 @@ extern DECLSPEC float SDLCALL SDL_GameControllerGetSensorDataRate(SDL_GameContro * The number of values and interpretation of the data is sensor dependent. * See SDL_sensor.h for the details for each type of sensor. * - * \param gamecontroller The controller to query - * \param type The type of sensor to query - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * \param gamecontroller The controller to query. + * \param type The type of sensor to query. + * \param data A pointer filled with the current sensor state. + * \param num_values The number of values to write to data. * \return 0 or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -928,12 +928,12 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorData(SDL_GameController * * The number of values and interpretation of the data is sensor dependent. * See SDL_sensor.h for the details for each type of sensor. * - * \param gamecontroller The controller to query - * \param type The type of sensor to query + * \param gamecontroller The controller to query. + * \param type The type of sensor to query. * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * current sensor reading if available, or 0 if not. + * \param data A pointer filled with the current sensor state. + * \param num_values The number of values to write to data. * \return 0 or -1 if an error occurred. * * \since This function is available since SDL 2.26.0. @@ -946,13 +946,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerGetSensorDataWithTimestamp(SDL_Gam * Each call to this function cancels any previous rumble effect, and calling * it with 0 intensity stops any rumbling. * - * \param gamecontroller The controller to vibrate + * \param gamecontroller The controller to vibrate. * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF + * rumble motor, from 0 to 0xFFFF. * \param high_frequency_rumble The intensity of the high frequency (right) - * rumble motor, from 0 to 0xFFFF - * \param duration_ms The duration of the rumble effect, in milliseconds - * \returns 0, or -1 if rumble isn't supported on this controller + * rumble motor, from 0 to 0xFFFF. + * \param duration_ms The duration of the rumble effect, in milliseconds. + * \returns 0, or -1 if rumble isn't supported on this controller. * * \since This function is available since SDL 2.0.9. * @@ -971,13 +971,13 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumble(SDL_GameController *gamecon * want the (more common) whole-controller rumble, use * SDL_GameControllerRumble() instead. * - * \param gamecontroller The controller to vibrate + * \param gamecontroller The controller to vibrate. * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF + * to 0xFFFF. * \param right_rumble The intensity of the right trigger rumble motor, from 0 - * to 0xFFFF - * \param duration_ms The duration of the rumble effect, in milliseconds - * \returns 0, or -1 if trigger rumble isn't supported on this controller + * to 0xFFFF. + * \param duration_ms The duration of the rumble effect, in milliseconds. + * \returns 0, or -1 if trigger rumble isn't supported on this controller. * * \since This function is available since SDL 2.0.14. * @@ -988,9 +988,9 @@ extern DECLSPEC int SDLCALL SDL_GameControllerRumbleTriggers(SDL_GameController /** * Query whether a game controller has an LED. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have a - * modifiable LED + * modifiable LED. * * \since This function is available since SDL 2.0.14. */ @@ -999,9 +999,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasLED(SDL_GameController *ga /** * Query whether a game controller has rumble support. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have rumble - * support + * support. * * \since This function is available since SDL 2.0.18. * @@ -1012,9 +1012,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumble(SDL_GameController /** * Query whether a game controller has rumble support on triggers. * - * \param gamecontroller The controller to query + * \param gamecontroller The controller to query. * \returns SDL_TRUE, or SDL_FALSE if this controller does not have trigger - * rumble support + * rumble support. * * \since This function is available since SDL 2.0.18. * @@ -1025,11 +1025,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GameControllerHasRumbleTriggers(SDL_GameCon /** * Update a game controller's LED color. * - * \param gamecontroller The controller to update - * \param red The intensity of the red LED - * \param green The intensity of the green LED - * \param blue The intensity of the blue LED - * \returns 0, or -1 if this controller does not have a modifiable LED + * \param gamecontroller The controller to update. + * \param red The intensity of the red LED. + * \param green The intensity of the green LED. + * \param blue The intensity of the blue LED. + * \returns 0, or -1 if this controller does not have a modifiable LED. * * \since This function is available since SDL 2.0.14. */ @@ -1038,11 +1038,11 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSetLED(SDL_GameController *gamecon /** * Send a controller specific effect packet * - * \param gamecontroller The controller to affect - * \param data The data to send to the controller - * \param size The size of the data to send to the controller + * \param gamecontroller The controller to affect. + * \param data The data to send to the controller. + * \param size The size of the data to send to the controller. * \returns 0, or -1 if this controller or driver doesn't support effect - * packets + * packets. * * \since This function is available since SDL 2.0.16. */ @@ -1052,7 +1052,7 @@ extern DECLSPEC int SDLCALL SDL_GameControllerSendEffect(SDL_GameController *gam * Close a game controller previously opened with SDL_GameControllerOpen(). * * \param gamecontroller a game controller identifier previously returned by - * SDL_GameControllerOpen() + * SDL_GameControllerOpen(). * * \since This function is available since SDL 2.0.0. * @@ -1064,9 +1064,9 @@ extern DECLSPEC void SDLCALL SDL_GameControllerClose(SDL_GameController *gamecon * Return the sfSymbolsName for a given button on a game controller on Apple * platforms. * - * \param gamecontroller the controller to query - * \param button a button on the game controller - * \returns the sfSymbolsName or NULL if the name can't be found + * \param gamecontroller the controller to query. + * \param button a button on the game controller. + * \returns the sfSymbolsName or NULL if the name can't be found. * * \since This function is available since SDL 2.0.18. * @@ -1078,9 +1078,9 @@ extern DECLSPEC const char* SDLCALL SDL_GameControllerGetAppleSFSymbolsNameForBu * Return the sfSymbolsName for a given axis on a game controller on Apple * platforms. * - * \param gamecontroller the controller to query - * \param axis an axis on the game controller - * \returns the sfSymbolsName or NULL if the name can't be found + * \param gamecontroller the controller to query. + * \param axis an axis on the game controller. + * \returns the sfSymbolsName or NULL if the name can't be found. * * \since This function is available since SDL 2.0.18. * diff --git a/include/SDL_gesture.h b/include/SDL_gesture.h index 685fdc5478..a39749a3ab 100644 --- a/include/SDL_gesture.h +++ b/include/SDL_gesture.h @@ -51,7 +51,7 @@ typedef Sint64 SDL_GestureID; * If the parameter `touchId` is -1 (i.e., all devices), this function will * always return 1, regardless of whether there actually are any devices. * - * \param touchId the touch device id, or -1 for all touch devices + * \param touchId the touch device id, or -1 for all touch devices. * \returns 1 on success or 0 if the specified device could not be found. * * \since This function is available since SDL 2.0.0. @@ -64,7 +64,7 @@ extern DECLSPEC int SDLCALL SDL_RecordGesture(SDL_TouchID touchId); /** * Save all currently loaded Dollar Gesture templates. * - * \param dst a SDL_RWops to save to + * \param dst a SDL_RWops to save to. * \returns the number of saved templates on success or 0 on failure; call * SDL_GetError() for more information. * @@ -78,8 +78,8 @@ extern DECLSPEC int SDLCALL SDL_SaveAllDollarTemplates(SDL_RWops *dst); /** * Save a currently loaded Dollar Gesture template. * - * \param gestureId a gesture id - * \param dst a SDL_RWops to save to + * \param gestureId a gesture id. + * \param dst a SDL_RWops to save to. * \returns 1 on success or 0 on failure; call SDL_GetError() for more * information. * @@ -94,8 +94,8 @@ extern DECLSPEC int SDLCALL SDL_SaveDollarTemplate(SDL_GestureID gestureId,SDL_R /** * Load Dollar Gesture templates from a file. * - * \param touchId a touch id - * \param src a SDL_RWops to load from + * \param touchId a touch id. + * \param src a SDL_RWops to load from. * \returns the number of loaded templates on success or a negative error code * (or 0) on failure; call SDL_GetError() for more information. * diff --git a/include/SDL_guid.h b/include/SDL_guid.h index 8b962a127f..7a36cd0a00 100644 --- a/include/SDL_guid.h +++ b/include/SDL_guid.h @@ -70,9 +70,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. * * \since This function is available since SDL 2.24.0. * @@ -87,7 +87,7 @@ extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int * 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 2.24.0. diff --git a/include/SDL_haptic.h b/include/SDL_haptic.h index 660f531156..f07804eaca 100644 --- a/include/SDL_haptic.h +++ b/include/SDL_haptic.h @@ -871,7 +871,7 @@ extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index); * autocenter will be disabled. To modify these values use SDL_HapticSetGain() * and SDL_HapticSetAutocenter(). * - * \param device_index index of the device to open + * \param device_index index of the device to open. * \returns the device identifier or NULL on failure; call SDL_GetError() for * more information. * @@ -891,7 +891,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpen(int device_index); /** * Check if the haptic device at the designated index has been opened. * - * \param device_index the index of the device to query + * \param device_index the index of the device to query. * \returns 1 if it has been opened, 0 if it hasn't or on failure; call * SDL_GetError() for more information. * @@ -905,7 +905,7 @@ extern DECLSPEC int SDLCALL SDL_HapticOpened(int device_index); /** * Get the index of a haptic device. * - * \param haptic the SDL_Haptic device to query + * \param haptic the SDL_Haptic device to query. * \returns the index of the specified haptic device or a negative error code * on failure; call SDL_GetError() for more information. * @@ -943,7 +943,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromMouse(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, SDL_FALSE if it isn't, or a * negative error code on failure; call SDL_GetError() for more * information. @@ -965,7 +965,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickIsHaptic(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. * @@ -981,7 +981,7 @@ extern DECLSPEC SDL_Haptic *SDLCALL SDL_HapticOpenFromJoystick(SDL_Joystick * /** * Close a haptic device previously opened with SDL_HapticOpen(). * - * \param haptic the SDL_Haptic device to close + * \param haptic the SDL_Haptic device to close. * * \since This function is available since SDL 2.0.0. * @@ -996,7 +996,7 @@ extern DECLSPEC void SDLCALL SDL_HapticClose(SDL_Haptic * haptic); * approximation. Always check to see if your created effect was actually * created and do not rely solely on SDL_HapticNumEffects(). * - * \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. * @@ -1012,7 +1012,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffects(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. @@ -1027,7 +1027,7 @@ extern DECLSPEC int SDLCALL SDL_HapticNumEffectsPlaying(SDL_Haptic * haptic); /** * 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. * @@ -1045,7 +1045,7 @@ extern DECLSPEC unsigned int SDLCALL SDL_HapticQuery(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. * @@ -1056,8 +1056,8 @@ extern DECLSPEC int SDLCALL SDL_HapticNumAxes(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 effect is supported, SDL_FALSE if it isn't, or a * negative error code on failure; call SDL_GetError() for more * information. @@ -1074,9 +1074,9 @@ extern DECLSPEC int SDLCALL SDL_HapticEffectSupported(SDL_Haptic * haptic, /** * 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. * @@ -1097,10 +1097,10 @@ extern DECLSPEC int SDLCALL SDL_HapticNewEffect(SDL_Haptic * haptic, * start playing from the start. You also cannot change the type either when * running SDL_HapticUpdateEffect(). * - * \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. * @@ -1123,10 +1123,10 @@ extern DECLSPEC int SDLCALL SDL_HapticUpdateEffect(SDL_Haptic * haptic, * 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. * @@ -1145,8 +1145,8 @@ extern DECLSPEC int SDLCALL SDL_HapticRunEffect(SDL_Haptic * haptic, * * * * - * \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. * @@ -1164,8 +1164,8 @@ extern DECLSPEC int SDLCALL SDL_HapticStopEffect(SDL_Haptic * haptic, * 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 2.0.0. * @@ -1179,8 +1179,8 @@ extern DECLSPEC void SDLCALL SDL_HapticDestroyEffect(SDL_Haptic * haptic, * * 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. * @@ -1202,8 +1202,9 @@ extern DECLSPEC int SDLCALL SDL_HapticGetEffectStatus(SDL_Haptic * haptic, * SDL_HapticSetGain() 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. * @@ -1221,8 +1222,8 @@ extern DECLSPEC int SDLCALL SDL_HapticSetGain(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. * @@ -1242,7 +1243,7 @@ extern DECLSPEC int SDLCALL SDL_HapticSetAutocenter(SDL_Haptic * haptic, * 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. * @@ -1257,7 +1258,7 @@ extern DECLSPEC int SDLCALL SDL_HapticPause(SDL_Haptic * haptic); * * Call to unpause after SDL_HapticPause(). * - * \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. * @@ -1270,7 +1271,7 @@ extern DECLSPEC int SDLCALL SDL_HapticUnpause(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. * @@ -1281,7 +1282,7 @@ extern DECLSPEC int SDLCALL SDL_HapticStopAll(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 effect is supported, SDL_FALSE if it isn't, or a * negative error code on failure; call SDL_GetError() for more * information. @@ -1297,7 +1298,7 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleSupported(SDL_Haptic * haptic); /** * 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. * @@ -1313,9 +1314,9 @@ extern DECLSPEC int SDLCALL SDL_HapticRumbleInit(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. * @@ -1330,7 +1331,7 @@ extern DECLSPEC int SDLCALL SDL_HapticRumblePlay(SDL_Haptic * haptic, float stre /** * 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/SDL_hidapi.h b/include/SDL_hidapi.h index f8bd2d2760..97752a7fcf 100644 --- a/include/SDL_hidapi.h +++ b/include/SDL_hidapi.h @@ -226,7 +226,7 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_id, * 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. * @@ -426,7 +426,7 @@ extern DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev, int /** * 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 2.0.18. */ diff --git a/include/SDL_hints.h b/include/SDL_hints.h index 15f2af691f..d4428b2c92 100644 --- a/include/SDL_hints.h +++ b/include/SDL_hints.h @@ -3097,9 +3097,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 2.0.0. @@ -3118,8 +3118,8 @@ extern 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 2.0.0. @@ -3137,7 +3137,7 @@ extern 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 2.24.0. @@ -3165,7 +3165,7 @@ extern DECLSPEC void SDLCALL SDL_ResetHints(void); /** * Get the value of a hint. * - * \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 2.0.0. @@ -3178,8 +3178,8 @@ extern 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. * @@ -3193,20 +3193,20 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetHintBoolean(const char *name, SDL_bool d /** * 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. */ typedef void (SDLCALL *SDL_HintCallback)(void *userdata, const char *name, const char *oldValue, const char *newValue); /** * Add a function to watch a particular hint. * - * \param name the hint to watch + * \param name the hint to watch. * \param callback An SDL_HintCallback function that will be called when the - * hint value changes - * \param userdata a pointer to pass to the callback function + * hint value changes. + * \param userdata a pointer to pass to the callback function. * * \since This function is available since SDL 2.0.0. * @@ -3219,10 +3219,10 @@ extern DECLSPEC void SDLCALL SDL_AddHintCallback(const char *name, /** * Remove a function watching a particular hint. * - * \param name the hint being watched + * \param name the hint being watched. * \param callback An SDL_HintCallback function that will be called when the - * hint value changes - * \param userdata a pointer being passed to the callback function + * hint value changes. + * \param userdata a pointer being passed to the callback function. * * \since This function is available since SDL 2.0.0. * diff --git a/include/SDL_joystick.h b/include/SDL_joystick.h index 863a3c16ce..c05afeae3b 100644 --- a/include/SDL_joystick.h +++ b/include/SDL_joystick.h @@ -182,7 +182,7 @@ extern DECLSPEC int SDLCALL SDL_NumJoysticks(void); * This can be called before any joysticks are opened. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system) + * on the system). * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -199,7 +199,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickNameForIndex(int device_index); * This can be called before any joysticks are opened. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system) + * on the system). * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -225,9 +225,9 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetDevicePlayerIndex(int device_index); * This function can be called before any joysticks are opened. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the GUID of the selected joystick. 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 2.0.0. * @@ -243,9 +243,9 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetDeviceGUID(int device_in * available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the USB vendor ID of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -258,9 +258,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceVendor(int device_index); * available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the USB product ID of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -273,9 +273,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProduct(int device_index); * isn't available this function returns 0. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the product version of the selected joystick. If called on an - * invalid index, this function returns zero + * invalid index, this function returns zero. * * \since This function is available since SDL 2.0.6. */ @@ -287,9 +287,9 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetDeviceProductVersion(int device_in * This can be called before any joysticks are opened. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the SDL_JoystickType of the selected joystick. If called on an - * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN` + * invalid index, this function returns `SDL_JOYSTICK_TYPE_UNKNOWN`. * * \since This function is available since SDL 2.0.6. */ @@ -301,7 +301,7 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetDeviceType(int device_in * This can be called before any joysticks are opened. * * \param device_index the index of the joystick to query (the N'th joystick - * on the system + * on the system. * \returns the instance id of the selected joystick. If called on an invalid * index, this function returns -1. * @@ -320,7 +320,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickGetDeviceInstanceID(int devic * The joystick subsystem must be initialized before a joystick can be opened * for use. * - * \param device_index the index of the joystick to query + * \param device_index the index of the joystick to query. * \returns a joystick identifier or NULL if an error occurred; call * SDL_GetError() for more information. * @@ -334,7 +334,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickOpen(int device_index); /** * Get the SDL_Joystick associated with an instance id. * - * \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; call SDL_GetError() * for more information. * @@ -345,7 +345,7 @@ extern DECLSPEC SDL_Joystick *SDLCALL SDL_JoystickFromInstanceID(SDL_JoystickID /** * 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. * @@ -419,7 +419,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickAttachVirtualEx(const SDL_VirtualJoystic * Detach a virtual joystick. * * \param device_index a value previously returned from - * SDL_JoystickAttachVirtual() + * SDL_JoystickAttachVirtual(). * \returns 0 on success, or -1 if an error occurred. * * \since This function is available since SDL 2.0.14. @@ -497,7 +497,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetVirtualHat(SDL_Joystick *joystick, in /** * Get the implementation dependent name of a joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the name of the selected joystick. If no name can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -511,7 +511,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickName(SDL_Joystick *joystick); /** * Get the implementation dependent path of a joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the path of the selected joystick. If no path can be found, this * function returns NULL; call SDL_GetError() for more information. * @@ -527,7 +527,7 @@ extern DECLSPEC const char *SDLCALL SDL_JoystickPath(SDL_Joystick *joystick); * For XInput controllers this returns the XInput user index. Many joysticks * will not be able to supply this information. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the player index, or -1 if it's not available. * * \since This function is available since SDL 2.0.9. @@ -537,7 +537,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetPlayerIndex(SDL_Joystick *joystick); /** * Set the player index of an opened joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \param player_index Player index to assign to this joystick, or -1 to clear * the player index and turn off player LEDs. * @@ -550,7 +550,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickSetPlayerIndex(SDL_Joystick *joystick, * * This function requires an open joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the GUID of the given joystick. If called on an invalid index, * this function returns a zero GUID; call SDL_GetError() for more * information. @@ -567,7 +567,7 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUID(SDL_Joystick *joyst * * If the vendor ID isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the USB vendor ID of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -579,7 +579,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetVendor(SDL_Joystick *joystick); * * If the product ID isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the USB product ID of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -591,7 +591,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProduct(SDL_Joystick *joystick); * * If the product version isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the product version of the selected joystick, or 0 if unavailable. * * \since This function is available since SDL 2.0.6. @@ -603,7 +603,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetProductVersion(SDL_Joystick *joyst * * If the firmware version isn't available this function returns 0. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the firmware version of the selected joystick, or 0 if * unavailable. * @@ -616,7 +616,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_JoystickGetFirmwareVersion(SDL_Joystick *joys * * Returns the serial number of the joystick, or NULL if it is not available. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the serial number of the selected joystick, or NULL if * unavailable. * @@ -627,7 +627,7 @@ extern DECLSPEC const char * SDLCALL SDL_JoystickGetSerial(SDL_Joystick *joystic /** * Get the type of an opened joystick. * - * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen() + * \param joystick the SDL_Joystick obtained from SDL_JoystickOpen(). * \returns the SDL_JoystickType of the selected joystick. * * \since This function is available since SDL 2.0.6. @@ -639,9 +639,9 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_JoystickGetType(SDL_Joystick *joyst * * 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. * * \since This function is available since SDL 2.0.0. * @@ -658,7 +658,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickGetGUIDString(SDL_JoystickGUID guid, ch * 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 2.0.0. @@ -670,15 +670,15 @@ extern DECLSPEC SDL_JoystickGUID SDLCALL SDL_JoystickGetGUIDFromString(const cha /** * Get the device information encoded in a SDL_JoystickGUID structure * - * \param guid the SDL_JoystickGUID you wish to get info about + * \param guid the SDL_JoystickGUID you wish to get info about. * \param vendor A pointer filled in with the device VID, or 0 if not - * available + * available. * \param product A pointer filled in with the device PID, or 0 if not - * available + * available. * \param version A pointer filled in with the device version, or 0 if not - * available + * 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 + * products with the same VID/PID, or 0 if not available. * * \since This function is available since SDL 2.26.0. * @@ -689,7 +689,7 @@ extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDInfo(SDL_JoystickGUID guid, Uint /** * 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. * @@ -703,7 +703,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAttached(SDL_Joystick *joystick) /** * Get the instance ID of an opened joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \param joystick an SDL_Joystick structure containing joystick information. * \returns the instance ID of the specified joystick on success or a negative * error code on failure; call SDL_GetError() for more information. * @@ -720,7 +720,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_JoystickInstanceID(SDL_Joystick *joys * 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. @@ -740,7 +740,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumAxes(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. * @@ -753,7 +753,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumBalls(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. * @@ -767,7 +767,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickNumHats(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. * @@ -809,7 +809,7 @@ extern DECLSPEC void SDLCALL SDL_JoystickUpdate(void); * If SDL was built with events disabled (extremely uncommon!), this will do * nothing and always return `SDL_IGNORE`. * - * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE` + * \param state can be one of `SDL_QUERY`, `SDL_IGNORE`, or `SDL_ENABLE`. * \returns If `state` is `SDL_QUERY` then the current state is returned, * otherwise `state` is returned (even if it was not one of the * allowed values). @@ -837,8 +837,8 @@ extern DECLSPEC int SDLCALL SDL_JoystickEventState(int state); * 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. * @@ -856,8 +856,8 @@ extern DECLSPEC Sint16 SDLCALL SDL_JoystickGetAxis(SDL_Joystick *joystick, * * 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 joystick an SDL_Joystick structure containing joystick information. + * \param axis the axis to query; the axis indices start at index 0. * \param state Upon return, the initial value is supplied here. * \return SDL_TRUE if this axis has any initial value, or SDL_FALSE if not. * @@ -896,8 +896,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickGetAxisInitialState(SDL_Joystick *j * - `SDL_HAT_LEFTUP` * - `SDL_HAT_LEFTDOWN` * - * \param joystick an SDL_Joystick structure containing joystick information - * \param hat the hat index to get the state from; 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 2.0.0. @@ -915,10 +915,10 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetHat(SDL_Joystick *joystick, * * 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. * @@ -932,9 +932,9 @@ extern DECLSPEC int SDLCALL SDL_JoystickGetBall(SDL_Joystick *joystick, /** * Get the current state of a button on a joystick. * - * \param joystick an SDL_Joystick structure containing joystick information + * \param joystick an SDL_Joystick structure containing joystick information. * \param button the button index to get the state from; indices start at - * index 0 + * index 0. * \returns 1 if the specified button is pressed, 0 otherwise. * * \since This function is available since SDL 2.0.0. @@ -950,13 +950,13 @@ extern DECLSPEC Uint8 SDLCALL SDL_JoystickGetButton(SDL_Joystick *joystick, * Each call to this function cancels any previous rumble effect, and calling * it with 0 intensity stops any rumbling. * - * \param joystick The joystick to vibrate + * \param joystick The joystick to vibrate. * \param low_frequency_rumble The intensity of the low frequency (left) - * rumble motor, from 0 to 0xFFFF + * rumble motor, from 0 to 0xFFFF. * \param high_frequency_rumble The intensity of the high frequency (right) - * 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 + * 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 2.0.9. * @@ -975,13 +975,13 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumble(SDL_Joystick *joystick, Uint16 lo * want the (more common) whole-controller rumble, use SDL_JoystickRumble() * instead. * - * \param joystick The joystick to vibrate + * \param joystick The joystick to vibrate. * \param left_rumble The intensity of the left trigger rumble motor, from 0 - * to 0xFFFF + * to 0xFFFF. * \param right_rumble The intensity of the right trigger rumble motor, from 0 - * to 0xFFFF - * \param duration_ms The duration of the rumble effect, in milliseconds - * \returns 0, or -1 if trigger rumble isn't supported on this joystick + * to 0xFFFF. + * \param duration_ms The duration of the rumble effect, in milliseconds. + * \returns 0, or -1 if trigger rumble isn't supported on this joystick. * * \since This function is available since SDL 2.0.14. * @@ -995,7 +995,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickRumbleTriggers(SDL_Joystick *joystick, U * An example of a joystick LED is the light on the back of a PlayStation 4's * DualShock 4 controller. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has a modifiable LED, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.14. @@ -1005,7 +1005,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasLED(SDL_Joystick *joystick); /** * Query whether a joystick has rumble support. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has rumble, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.18. @@ -1017,7 +1017,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumble(SDL_Joystick *joystick); /** * Query whether a joystick has rumble support on triggers. * - * \param joystick The joystick to query + * \param joystick The joystick to query. * \return SDL_TRUE if the joystick has trigger rumble, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.18. @@ -1032,11 +1032,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joy * An example of a joystick LED is the light on the back of a PlayStation 4's * DualShock 4 controller. * - * \param joystick The joystick to update - * \param red The intensity of the red LED - * \param green The intensity of the green LED - * \param blue The intensity of the blue LED - * \returns 0 on success, -1 if this joystick does not have a modifiable LED + * \param joystick The joystick to update. + * \param red The intensity of the red LED. + * \param green The intensity of the green LED. + * \param blue The intensity of the blue LED. + * \returns 0 on success, -1 if this joystick does not have a modifiable LED. * * \since This function is available since SDL 2.0.14. */ @@ -1045,10 +1045,11 @@ extern DECLSPEC int SDLCALL SDL_JoystickSetLED(SDL_Joystick *joystick, Uint8 red /** * 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 - * \returns 0, or -1 if this joystick or driver doesn't support effect packets + * \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, or -1 if this joystick or driver doesn't support effect + * packets. * * \since This function is available since SDL 2.0.16. */ @@ -1057,7 +1058,7 @@ extern DECLSPEC int SDLCALL SDL_JoystickSendEffect(SDL_Joystick *joystick, const /** * Close a joystick previously opened with SDL_JoystickOpen(). * - * \param joystick The joystick device to close + * \param joystick The joystick device to close. * * \since This function is available since SDL 2.0.0. * @@ -1068,9 +1069,9 @@ extern DECLSPEC void SDLCALL SDL_JoystickClose(SDL_Joystick *joystick); /** * Get the battery level of a joystick as SDL_JoystickPowerLevel. * - * \param joystick the SDL_Joystick to query + * \param joystick the SDL_Joystick to query. * \returns the current battery level as SDL_JoystickPowerLevel on success or - * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown + * `SDL_JOYSTICK_POWER_UNKNOWN` if it is unknown. * * \since This function is available since SDL 2.0.4. */ diff --git a/include/SDL_keyboard.h b/include/SDL_keyboard.h index 21ef8c09fb..eb24a65058 100644 --- a/include/SDL_keyboard.h +++ b/include/SDL_keyboard.h @@ -85,7 +85,7 @@ extern 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 2.0.0. @@ -130,7 +130,7 @@ extern 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 2.0.0. * @@ -144,7 +144,7 @@ extern 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 2.0.0. @@ -160,7 +160,7 @@ extern DECLSPEC SDL_Keycode SDLCALL SDL_GetKeyFromScancode(SDL_Scancode scancode * * 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 2.0.0. @@ -184,7 +184,7 @@ extern 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 (""). * @@ -198,7 +198,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetScancodeName(SDL_Scancode scancode); /** * 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. * @@ -215,7 +215,7 @@ extern DECLSPEC SDL_Scancode SDLCALL SDL_GetScancodeFromName(const char *name); * * See SDL_Scancode and SDL_Keycode for details. * - * \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 @@ -232,7 +232,7 @@ extern 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. * @@ -317,7 +317,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsTextInputShown(void); * any feedback. * * \param rect the SDL_Rect structure representing the rectangle to receive - * text (ignored if NULL) + * text (ignored if NULL). * * \since This function is available since SDL 2.0.0. * @@ -341,7 +341,7 @@ extern 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 2.0.0. diff --git a/include/SDL_loadso.h b/include/SDL_loadso.h index 61b75b266e..550a7a52a8 100644 --- a/include/SDL_loadso.h +++ b/include/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 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. * @@ -97,7 +97,7 @@ extern DECLSPEC void *SDLCALL SDL_LoadFunction(void *handle, /** * 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 2.0.0. * diff --git a/include/SDL_log.h b/include/SDL_log.h index ab6c6248a3..f46f5ec725 100644 --- a/include/SDL_log.h +++ b/include/SDL_log.h @@ -114,7 +114,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 2.0.0. * @@ -125,8 +125,8 @@ extern DECLSPEC void SDLCALL SDL_LogSetAllPriority(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 2.0.0. * @@ -139,8 +139,8 @@ extern DECLSPEC void SDLCALL SDL_LogSetPriority(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 2.0.0. * @@ -166,7 +166,7 @@ extern DECLSPEC void SDLCALL SDL_LogResetPriorities(void); * = * \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 2.0.0. * @@ -184,10 +184,10 @@ extern DECLSPEC void SDLCALL SDL_Log(SDL_PRINTF_FORMAT_STRING const char *fmt, . /** * 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 2.0.0. * @@ -205,10 +205,10 @@ extern DECLSPEC void SDLCALL SDL_LogVerbose(int category, SDL_PRINTF_FORMAT_STRI /** * 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 2.0.0. * @@ -226,10 +226,10 @@ extern DECLSPEC void SDLCALL SDL_LogDebug(int category, SDL_PRINTF_FORMAT_STRING /** * 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 2.0.0. * @@ -247,10 +247,10 @@ extern DECLSPEC void SDLCALL SDL_LogInfo(int category, SDL_PRINTF_FORMAT_STRING /** * 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 2.0.0. * @@ -268,10 +268,10 @@ extern DECLSPEC void SDLCALL SDL_LogWarn(int category, SDL_PRINTF_FORMAT_STRING /** * 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 2.0.0. * @@ -289,10 +289,10 @@ extern DECLSPEC void SDLCALL SDL_LogError(int category, SDL_PRINTF_FORMAT_STRING /** * 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 2.0.0. * @@ -310,11 +310,11 @@ extern DECLSPEC void SDLCALL SDL_LogCritical(int category, SDL_PRINTF_FORMAT_STR /** * 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 2.0.0. * @@ -334,10 +334,10 @@ extern 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 2.0.0. * @@ -359,10 +359,11 @@ extern 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_LogSetOutputFunction() - * \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_LogSetOutputFunction(). + * \param category the category of the message. + * \param priority the priority of the message. + * \param message the message being output. */ typedef void (SDLCALL *SDL_LogOutputFunction)(void *userdata, int category, SDL_LogPriority priority, const char *message); @@ -370,9 +371,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 2.0.0. * @@ -383,8 +384,8 @@ extern DECLSPEC void SDLCALL SDL_LogGetOutputFunction(SDL_LogOutputFunction *cal /** * 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 2.0.0. * diff --git a/include/SDL_main.h b/include/SDL_main.h index 7695ce32df..36ce1bab84 100644 --- a/include/SDL_main.h +++ b/include/SDL_main.h @@ -222,8 +222,8 @@ extern DECLSPEC void SDLCALL SDL_UnregisterApp(void); /** * Initialize and launch an SDL/WinRT application. * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func - * \param reserved reserved for future use; should be NULL + * \param mainFunction the SDL app's C-style main(), an SDL_main_func. + * \param reserved reserved for future use; should be NULL. * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve * more information on the failure. * @@ -238,10 +238,10 @@ extern DECLSPEC int SDLCALL SDL_WinRTRunApp(SDL_main_func mainFunction, void * r /** * Initializes and launches an SDL application. * - * \param argc The argc parameter from the application's main() function - * \param argv The argv parameter from the application's main() function - * \param mainFunction The SDL app's C-style main(), an SDL_main_func - * \return the return value from mainFunction + * \param argc The argc parameter from the application's main() function. + * \param argv The argv parameter from the application's main() function. + * \param mainFunction The SDL app's C-style main(), an SDL_main_func. + * \return the return value from mainFunction. * * \since This function is available since SDL 2.0.10. */ @@ -254,8 +254,8 @@ extern DECLSPEC int SDLCALL SDL_UIKitRunApp(int argc, char *argv[], SDL_main_fun /** * Initialize and launch an SDL GDK application. * - * \param mainFunction the SDL app's C-style main(), an SDL_main_func - * \param reserved reserved for future use; should be NULL + * \param mainFunction the SDL app's C-style main(), an SDL_main_func. + * \param reserved reserved for future use; should be NULL. * \returns 0 on success or -1 on failure; call SDL_GetError() to retrieve * more information on the failure. * diff --git a/include/SDL_messagebox.h b/include/SDL_messagebox.h index 8e368a1ea7..4d46db0e7c 100644 --- a/include/SDL_messagebox.h +++ b/include/SDL_messagebox.h @@ -130,8 +130,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. * @@ -170,10 +171,10 @@ extern DECLSPEC int SDLCALL SDL_ShowMessageBox(const SDL_MessageBoxData *message * 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/SDL_metal.h b/include/SDL_metal.h index cb4d7d353e..90b5a6f52f 100644 --- a/include/SDL_metal.h +++ b/include/SDL_metal.h @@ -91,9 +91,9 @@ extern DECLSPEC void *SDLCALL SDL_Metal_GetLayer(SDL_MetalView view); * Get the size of a window's underlying drawable in pixels (for use with * setting viewport, scissor & etc). * - * \param window SDL_Window from which the drawable size should be queried - * \param w Pointer to variable for storing the width in pixels, may be NULL - * \param h Pointer to variable for storing the height in pixels, may be NULL + * \param window SDL_Window from which the drawable size should be queried. + * \param w Pointer to variable for storing the width in pixels, may be NULL. + * \param h Pointer to variable for storing the height in pixels, may be NULL. * * \since This function is available since SDL 2.0.14. * diff --git a/include/SDL_mouse.h b/include/SDL_mouse.h index b04e37551c..bdf7e25b77 100644 --- a/include/SDL_mouse.h +++ b/include/SDL_mouse.h @@ -90,9 +90,9 @@ extern 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 2.0.0. @@ -120,9 +120,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetMouseState(int *x, int *y); * 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. * @@ -141,8 +141,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetGlobalMouseState(int *x, int *y); * 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 2.0.0. @@ -162,9 +162,9 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetRelativeMouseState(int *x, int *y); * 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 2.0.0. * @@ -184,8 +184,8 @@ extern 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. * @@ -297,14 +297,14 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetRelativeMouseMode(void); * Also, since SDL 2.0.0, SDL_CreateSystemCursor() is available, which * provides twelve 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 location of the upper left corner of the cursor - * relative to the actual mouse position + * relative to the actual mouse position. * \param hot_y the Y-axis location of the upper left corner of the cursor - * relative to the actual mouse position + * relative to the actual mouse position. * \returns a new cursor with the specified parameters on success or NULL on * failure; call SDL_GetError() for more information. * @@ -322,9 +322,9 @@ extern 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. * @@ -340,7 +340,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateColorCursor(SDL_Surface *surface, /** * 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. * @@ -358,7 +358,7 @@ extern DECLSPEC SDL_Cursor *SDLCALL SDL_CreateSystemCursor(SDL_SystemCursor id); * 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. * * \since This function is available since SDL 2.0.0. * @@ -402,7 +402,7 @@ extern 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 2.0.0. * diff --git a/include/SDL_mutex.h b/include/SDL_mutex.h index 2d615ae2cb..b754611e59 100644 --- a/include/SDL_mutex.h +++ b/include/SDL_mutex.h @@ -165,7 +165,7 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void); * unlock it the same number of times before it is actually made available for * other threads in the system (this is known as a "recursive mutex"). * - * \param mutex the mutex to lock + * \param mutex the mutex to lock. * \return 0, or -1 on error. * * \since This function is available since SDL 2.0.0. @@ -182,7 +182,7 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex); * This technique is useful if you need exclusive access to a resource but * don't want to wait for it, and will return to it to try again later. * - * \param mutex the mutex to try to lock + * \param mutex the mutex to try to lock. * \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for * more information. * @@ -224,7 +224,7 @@ extern DECLSPEC int SDLCALL SDL_UnlockMutex(SDL_mutex * mutex) SDL_RELEASE(mutex * 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 2.0.0. * @@ -256,7 +256,7 @@ typedef struct SDL_semaphore SDL_sem; * 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. * @@ -277,7 +277,7 @@ extern DECLSPEC SDL_sem *SDLCALL SDL_CreateSemaphore(Uint32 initial_value); * 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 2.0.0. * @@ -301,7 +301,7 @@ extern DECLSPEC void SDLCALL SDL_DestroySemaphore(SDL_sem * sem); * This function is the equivalent of calling SDL_SemWaitTimeout() with a time * length of `SDL_MUTEX_MAXWAIT`. * - * \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. * @@ -325,7 +325,7 @@ extern DECLSPEC int SDLCALL SDL_SemWait(SDL_sem * 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. @@ -349,8 +349,8 @@ extern DECLSPEC int SDLCALL SDL_SemTryWait(SDL_sem * 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 timeout the length of the timeout, in milliseconds + * \param sem the semaphore to wait on. + * \param timeout 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. @@ -369,7 +369,7 @@ extern DECLSPEC int SDLCALL SDL_SemWaitTimeout(SDL_sem *sem, Uint32 timeout); /** * 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. * @@ -387,7 +387,7 @@ extern DECLSPEC int SDLCALL SDL_SemPost(SDL_sem * 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 2.0.0. @@ -427,7 +427,7 @@ extern DECLSPEC SDL_cond *SDLCALL SDL_CreateCond(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 2.0.0. * @@ -442,7 +442,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyCond(SDL_cond * 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. * @@ -459,7 +459,7 @@ extern DECLSPEC int SDLCALL SDL_CondSignal(SDL_cond * 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. * @@ -486,8 +486,8 @@ extern DECLSPEC int SDLCALL SDL_CondBroadcast(SDL_cond * cond); * This function is the equivalent of calling SDL_CondWaitTimeout() with a * time length of `SDL_MUTEX_MAXWAIT`. * - * \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. * @@ -512,10 +512,10 @@ extern DECLSPEC int SDLCALL SDL_CondWait(SDL_cond * cond, SDL_mutex * mutex); * * The mutex must be locked before calling this function. * - * \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 ms the maximum time to wait, in milliseconds, or `SDL_MUTEX_MAXWAIT` - * to wait indefinitely + * to wait 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/SDL_pixels.h b/include/SDL_pixels.h index 1a2af49ec8..bed90faee6 100644 --- a/include/SDL_pixels.h +++ b/include/SDL_pixels.h @@ -394,7 +394,7 @@ typedef struct SDL_PixelFormat /** * Get the human readable name of a pixel format. * - * \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. * @@ -405,12 +405,12 @@ extern DECLSPEC const char* SDLCALL SDL_GetPixelFormatName(Uint32 format); /** * 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. * @@ -431,12 +431,12 @@ extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, * 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 - * \returns one of the SDL_PixelFormatEnum values + * \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 one of the SDL_PixelFormatEnum values. * * \since This function is available since SDL 2.0.0. * @@ -455,7 +455,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, * 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. * @@ -468,7 +468,7 @@ extern DECLSPEC SDL_PixelFormat * SDLCALL SDL_AllocFormat(Uint32 pixel_format); /** * Free an SDL_PixelFormat structure allocated by SDL_AllocFormat(). * - * \param format the SDL_PixelFormat structure to free + * \param format the SDL_PixelFormat structure to free. * * \since This function is available since SDL 2.0.0. * @@ -481,7 +481,7 @@ extern DECLSPEC void SDLCALL SDL_FreeFormat(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. @@ -495,8 +495,8 @@ extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(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. * @@ -511,10 +511,10 @@ extern DECLSPEC int SDLCALL SDL_SetPixelFormatPalette(SDL_PixelFormat * format, /** * 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 if not all of the colors * could be set; call SDL_GetError() for more information. * @@ -530,7 +530,7 @@ extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, /** * Free a palette created with SDL_AllocPalette(). * - * \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 2.0.0. * @@ -556,11 +556,11 @@ extern DECLSPEC void SDLCALL SDL_FreePalette(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 2.0.0. * @@ -590,12 +590,12 @@ extern 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 2.0.0. * @@ -615,12 +615,12 @@ extern 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 2.0.0. * @@ -643,13 +643,13 @@ extern 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 2.0.0. * @@ -665,8 +665,8 @@ extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, /** * Calculate a 256 entry gamma ramp for a gamma value. * - * \param gamma a gamma value where 0.0 is black and 1.0 is identity - * \param ramp an array of 256 values filled in with the gamma ramp + * \param gamma a gamma value where 0.0 is black and 1.0 is identity. + * \param ramp an array of 256 values filled in with the gamma ramp. * * \since This function is available since SDL 2.0.0. * diff --git a/include/SDL_power.h b/include/SDL_power.h index af19b21fab..c96b1a3dd3 100644 --- a/include/SDL_power.h +++ b/include/SDL_power.h @@ -66,10 +66,10 @@ typedef enum SDL_PowerState * * \param seconds seconds of battery life left, you can pass a NULL here if * you don't care, will return -1 if we can't determine a - * value, or we're not running on a battery + * value, or we're not running on a battery. * \param percent percentage of battery life left, between 0 and 100, you can * pass a NULL here if you don't care, will return -1 if we - * can't determine a value, or we're not running on a battery + * can't determine a value, or we're not running on a battery. * \returns an SDL_PowerState enum representing the current battery state. * * \since This function is available since SDL 2.0.0. diff --git a/include/SDL_rect.h b/include/SDL_rect.h index c7307eb258..7a262aef43 100644 --- a/include/SDL_rect.h +++ b/include/SDL_rect.h @@ -135,8 +135,8 @@ SDL_FORCE_INLINE SDL_bool SDL_RectEquals(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. * * \since This function is available since SDL 2.0.0. @@ -151,10 +151,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(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 2.0.0. @@ -168,10 +168,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectRect(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`. * * \since This function is available since SDL 2.0.0. */ @@ -186,11 +186,11 @@ extern DECLSPEC void SDLCALL SDL_UnionRect(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. * @@ -210,11 +210,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EnclosePoints(const SDL_Point * points, * 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 2.0.0. @@ -274,8 +274,8 @@ SDL_FORCE_INLINE SDL_bool SDL_FRectEquals(const SDL_FRect *a, const SDL_FRect *b * * 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 2.0.22. @@ -290,10 +290,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersectionF(const SDL_FRect * A, * * 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 2.0.22. @@ -307,10 +307,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IntersectFRect(const SDL_FRect * A, /** * 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`. * * \since This function is available since SDL 2.0.22. */ @@ -326,11 +326,11 @@ extern DECLSPEC void SDLCALL SDL_UnionFRect(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. * @@ -351,11 +351,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_EncloseFPoints(const SDL_FPoint * points, * 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 2.0.22. diff --git a/include/SDL_render.h b/include/SDL_render.h index 262f85916e..fda3c6506b 100644 --- a/include/SDL_render.h +++ b/include/SDL_render.h @@ -172,9 +172,9 @@ extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void); /** * Get info about a specific 2D rendering driver for the current display. * - * \param index the index of the driver to query information about + * \param index the index of the driver to query information about. * \param info an SDL_RendererInfo structure to be filled with information on - * the rendering driver + * the rendering driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -189,12 +189,12 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index, /** * Create a window and default renderer. * - * \param width the width of the window - * \param height the height of the window + * \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 -1 on error; call SDL_GetError() for more * information. * @@ -211,10 +211,10 @@ extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer( /** * Create a 2D rendering context for a window. * - * \param window the window where rendering is displayed + * \param window the window where rendering is displayed. * \param index the index of the rendering driver to initialize, or -1 to - * initialize the first one supporting the requested flags - * \param flags 0, or one or more SDL_RendererFlags OR'd together + * initialize the first one supporting the requested flags. + * \param flags 0, or one or more SDL_RendererFlags OR'd together. * \returns a valid rendering context or NULL if there was an error; call * SDL_GetError() for more information. * @@ -237,7 +237,7 @@ extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window, * 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. * @@ -252,7 +252,7 @@ extern 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. * @@ -265,7 +265,7 @@ extern 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. * @@ -276,9 +276,9 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_RenderGetWindow(SDL_Renderer *renderer) /** * Get information about a rendering context. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param info an SDL_RendererInfo structure filled with information about the - * current renderer + * current renderer. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -296,9 +296,9 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer, * has more pixels than the window that contains it, so use this instead of * SDL_GetWindowSize() to decide how much drawing area you have. * - * \param renderer the rendering context - * \param w an int filled with the width - * \param h an int filled with the height + * \param renderer the rendering context. + * \param w an int filled with the width. + * \param h an int filled with the height. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -315,11 +315,11 @@ extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer, * You can set the texture scaling method by setting * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture. * - * \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. @@ -348,9 +348,9 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer, * format of the surface. Use SDL_QueryTexture() to query the pixel format of * the texture. * - * \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. * @@ -365,7 +365,7 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer /** * Query the attributes of a texture. * - * \param texture the texture to query + * \param texture the texture to query. * \param format a pointer filled in with the raw format of the texture; the * actual format may differ, but pixel transfers will use this * format (one of the SDL_PixelFormatEnum values). This argument @@ -400,10 +400,10 @@ extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture, * 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. * @@ -419,10 +419,10 @@ extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(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. * @@ -446,8 +446,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(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. * @@ -462,8 +462,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(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. * @@ -481,8 +481,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(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. * @@ -497,8 +497,8 @@ extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture, /** * 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. * @@ -580,12 +580,12 @@ extern DECLSPEC void * SDLCALL SDL_GetTextureUserData(SDL_Texture * texture); * 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. * @@ -607,18 +607,18 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture, * 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 -1 if the texture is not valid; call * SDL_GetError() for more information. * @@ -639,7 +639,7 @@ extern 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. @@ -669,13 +669,13 @@ extern 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. @@ -707,13 +707,13 @@ extern 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 was 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 -1 if the texture is not valid or was not created - * with `SDL_TEXTUREACCESS_STREAMING` + * with `SDL_TEXTUREACCESS_STREAMING`. * * \since This function is available since SDL 2.0.12. * @@ -735,7 +735,7 @@ extern 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 2.0.0. * @@ -746,7 +746,7 @@ extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture); /** * Determine whether a renderer supports the use of render targets. * - * \param renderer the renderer that will be checked + * \param renderer the renderer that will be checked. * \returns SDL_TRUE if supported or SDL_FALSE if not. * * \since This function is available since SDL 2.0.0. @@ -766,7 +766,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *rendere * 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. @@ -786,7 +786,7 @@ extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, * 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 2.0.0. @@ -811,9 +811,9 @@ extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer * If this function results in scaling or subpixel drawing by the rendering * backend, it will be handled using the appropriate quality hints. * - * \param renderer the renderer for which resolution should be set - * \param w the width of the logical resolution - * \param h the height of the logical resolution + * \param renderer the renderer for which resolution should be set. + * \param w the width of the logical resolution. + * \param h the height of the logical resolution. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -834,9 +834,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, in * When using a target texture: Never return 0 for `w` and `h` at first. Then * it returns the logical width and height that are set. * - * \param renderer a rendering context - * \param w an int to be filled with the width - * \param h an int to be filled with the height + * \param renderer a rendering context. + * \param w an int to be filled with the width. + * \param h an int to be filled with the height. * * \since This function is available since SDL 2.0.0. * @@ -851,8 +851,8 @@ extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, i * when a resolution is between two multiples of a logical size, the viewport * size is rounded down to the lower multiple. * - * \param renderer the renderer for which integer scaling should be set - * \param enable enable or disable the integer scaling for rendering + * \param renderer the renderer for which integer scaling should be set. + * \param enable enable or disable the integer scaling for rendering. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -867,7 +867,7 @@ extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer, /** * Get whether integer scales are forced for resolution-independent rendering. * - * \param renderer the renderer from which integer scaling should be queried + * \param renderer the renderer from which integer scaling should be queried. * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on * failure; call SDL_GetError() for more information. * @@ -883,9 +883,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * render * When the window is resized, the viewport is reset to fill the entire new * window size. * - * \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. * @@ -899,8 +899,8 @@ extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer, /** * 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. * * \since This function is available since SDL 2.0.0. * @@ -913,9 +913,9 @@ extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer, * Set the clip rectangle for rendering on the specified target. * * \param renderer the rendering context for which clip rectangle should be - * set + * set. * \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. * @@ -931,9 +931,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer, * Get the clip rectangle for the current target. * * \param renderer the rendering context from which clip rectangle should be - * queried + * queried. * \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. * * \since This function is available since SDL 2.0.0. * @@ -946,7 +946,7 @@ extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer, /** * Get whether clipping is enabled on the given renderer. * - * \param renderer the renderer from which clip state should be queried + * \param renderer the renderer from which clip state should be queried. * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call * SDL_GetError() for more information. * @@ -969,9 +969,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer * will be handled using the appropriate quality hints. For best results use * integer scaling factors. * - * \param renderer a rendering context - * \param scaleX the horizontal scaling factor - * \param scaleY the vertical scaling factor + * \param renderer a 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. * @@ -986,9 +986,9 @@ extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer, /** * Get the drawing scale for the current target. * - * \param renderer the renderer from which drawing scale should be queried - * \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 renderer from which drawing scale should be queried. + * \param scaleX a pointer filled in with the horizontal scaling factor. + * \param scaleY a pointer filled in with the vertical scaling factor. * * \since This function is available since SDL 2.0.0. * @@ -1005,11 +1005,11 @@ extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer, * and logical renderer size set * * \param renderer the renderer from which the logical coordinates should be - * calculated - * \param windowX the real X coordinate in the window - * \param windowY the real Y coordinate in the window - * \param logicalX the pointer filled with the logical x coordinate - * \param logicalY the pointer filled with the logical y coordinate + * calculated. + * \param windowX the real X coordinate in the window. + * \param windowY the real Y coordinate in the window. + * \param logicalX the pointer filled with the logical x coordinate. + * \param logicalY the pointer filled with the logical y coordinate. * * \since This function is available since SDL 2.0.18. * @@ -1031,11 +1031,11 @@ extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer, * and logical renderer size set * * \param renderer the renderer from which the window coordinates should be - * calculated - * \param logicalX the logical x coordinate - * \param logicalY the logical y coordinate - * \param windowX the pointer filled with the real X coordinate in the window - * \param windowY the pointer filled with the real Y coordinate in the window + * calculated. + * \param logicalX the logical x coordinate. + * \param logicalY the logical y coordinate. + * \param windowX the pointer filled with the real X coordinate in the window. + * \param windowY the pointer filled with the real Y coordinate in the window. * * \since This function is available since SDL 2.0.18. * @@ -1054,13 +1054,13 @@ extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer, * 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. * @@ -1084,15 +1084,15 @@ extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer, /** * 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. * @@ -1109,8 +1109,8 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(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. * @@ -1132,8 +1132,8 @@ extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer, /** * 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. * @@ -1150,7 +1150,7 @@ extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer, * This function clears the entire rendering target, ignoring the viewport and * the clip rectangle. * - * \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. * @@ -1166,9 +1166,9 @@ extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer); * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple, * use SDL_RenderDrawPoints() instead. * - * \param renderer the rendering context - * \param x the x coordinate of the point - * \param y the y coordinate of the point + * \param renderer the rendering context. + * \param x the x coordinate of the point. + * \param y the y coordinate of the point. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1191,10 +1191,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer, /** * Draw multiple points on the current rendering target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param points an array of SDL_Point structures that represent the points to - * draw - * \param count the number of points to draw + * 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. * @@ -1221,11 +1221,11 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer, * SDL_RenderDrawLine() draws the line to include both end points. If you want * to draw multiple, connecting lines use SDL_RenderDrawLines() instead. * - * \param renderer the rendering context - * \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 + * \param renderer the rendering context. + * \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 a negative error code on failure; call * SDL_GetError() for more information. * @@ -1248,10 +1248,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer, /** * Draw a series of connected lines on the current rendering target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param points an array of SDL_Point structures representing points along - * the lines - * \param count the number of points, drawing count-1 lines + * 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. * @@ -1275,9 +1275,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer, /** * Draw a rectangle on the current rendering target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the rectangle to draw, or - * NULL to outline the entire rendering target + * NULL to outline the entire rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1300,10 +1300,10 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer, /** * Draw some number of rectangles on the current rendering target. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rects an array of SDL_Rect structures representing the rectangles to - * be drawn - * \param count the number of rectangles + * be drawn. + * \param count the number of rectangles. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1331,9 +1331,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer, * color's alpha value is ignored unless blending is enabled with the * appropriate call to SDL_SetRenderDrawBlendMode(). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect the SDL_Rect structure representing the rectangle to fill, or - * NULL for the entire rendering target + * NULL for the entire rendering target. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1357,10 +1357,10 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer, * Fill some number of rectangles on the current rendering target with the * drawing color. * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rects an array of SDL_Rect structures representing the rectangles to - * be filled - * \param count the number of rectangles + * be filled. + * \param count the number of rectangles. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1391,12 +1391,13 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer, * The texture alpha is affected based on its alpha modulation set by * SDL_SetTextureAlphaMod(). * - * \param renderer the rendering context - * \param texture the source texture - * \param srcrect the source SDL_Rect structure or NULL for the entire texture + * \param renderer the rendering context. + * \param texture the source texture. + * \param srcrect the source SDL_Rect structure or NULL for the entire + * texture. * \param dstrect the destination SDL_Rect structure or NULL for the entire * rendering target; the texture will be stretched to fill the - * given rectangle + * given rectangle. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1429,18 +1430,19 @@ extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer, * The texture alpha is affected based on its alpha modulation set by * SDL_SetTextureAlphaMod(). * - * \param renderer the rendering context - * \param texture the source texture - * \param srcrect the source SDL_Rect structure or NULL for the entire texture + * \param renderer the rendering context. + * \param texture the source texture. + * \param srcrect the source SDL_Rect structure or NULL for the entire + * texture. * \param dstrect the destination SDL_Rect structure or NULL for the entire - * rendering target + * rendering target. * \param angle an angle in degrees that indicates the rotation that will be - * applied to dstrect, rotating it in a clockwise direction + * 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`) + * around `dstrect.w / 2`, `dstrect.h / 2`). * \param flip a SDL_RendererFlip value stating which flipping actions should - * be performed on the texture + * be performed on the texture. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1466,7 +1468,7 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer, * \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. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1477,9 +1479,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer, * 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 - * \return 0 on success, or -1 on error + * \param points The points to draw. + * \param count The number of points to draw. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1495,7 +1497,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer, * \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. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1507,9 +1509,9 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer, * 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 - * \return 0 on success, or -1 on error + * \param points The points along the lines. + * \param count The number of points, drawing count-1 lines. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1523,7 +1525,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer, * \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. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1537,7 +1539,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer, * \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. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1552,7 +1554,7 @@ extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer, * \param renderer The renderer which should fill a rectangle. * \param rect A pointer to the destination rectangle, or NULL for the entire * rendering target. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1566,7 +1568,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer, * \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. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1584,7 +1586,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer, * texture. * \param dstrect A pointer to the destination rectangle, or NULL for the * entire rendering target. - * \return 0 on success, or -1 on error + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1604,13 +1606,13 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer, * \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 + * 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_RendererFlip value stating which flipping actions should - * be performed on the texture - * \return 0 on success, or -1 on error + * be performed on the texture. + * \return 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.10. */ @@ -1635,7 +1637,7 @@ extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer, * array, if NULL all vertices will be rendered in sequential * order. * \param num_indices Number of indices. - * \return 0 on success, or -1 if the operation is not supported + * \return 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.18. * @@ -1654,18 +1656,18 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer, * * \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 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) - * \return 0 on success, or -1 if the operation is not supported + * \param size_indices Index size: 1 (byte), 2 (short), 4 (int). + * \return 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.18. * @@ -1694,13 +1696,13 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer, * but it might contain additional padding (for example, 24bit RGB Windows * Bitmap data pads all rows to multiples of 4 bytes). * - * \param renderer the rendering context + * \param renderer the rendering context. * \param rect an SDL_Rect structure representing the area to read, or NULL - * for the entire render target + * for the entire render target. * \param format an SDL_PixelFormatEnum value of the desired format of the - * pixel data, or 0 to use the format of the rendering target - * \param pixels a pointer to the pixel data to copy into - * \param pitch the pitch of the `pixels` parameter + * pixel data, or 0 to use the format of the rendering target. + * \param pixels a pointer to the pixel data to copy into. + * \param pitch the pitch of the `pixels` parameter. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1730,7 +1732,7 @@ extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer, * starting each new frame's drawing, even if you plan to overwrite every * pixel. * - * \param renderer the rendering context + * \param renderer the rendering context. * * \threadsafety You may only call this function on the main thread. If this * happens to work on a background thread on any given platform @@ -1759,7 +1761,7 @@ extern DECLSPEC void 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 2.0.0. * @@ -1774,7 +1776,7 @@ extern 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 2.0.0. * @@ -1805,7 +1807,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer); * and earlier, as earlier versions did not queue rendering commands at all, * instead flushing them to the OS immediately. * - * \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. * @@ -1836,11 +1838,11 @@ extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer); * re-order the color channels in the shaders phase, so the uploaded texture * may have swapped color channels. * - * \param texture the texture to bind to the current OpenGL/ES/ES2 context + * \param texture the texture to bind to the current OpenGL/ES/ES2 context. * \param texw a pointer to a float value which will be filled with the - * texture width or NULL if you don't need that value + * texture width or NULL if you don't need that value. * \param texh a pointer to a float value which will be filled with the - * texture height or NULL if you don't need that value + * texture height or NULL if you don't need that value. * \returns 0 on success, or -1 if the operation is not supported; call * SDL_GetError() for more information. * @@ -1856,8 +1858,9 @@ extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw * * See SDL_GL_BindTexture() for examples on how to use these functions * - * \param texture the texture to unbind from the current OpenGL/ES/ES2 context - * \returns 0 on success, or -1 if the operation is not supported + * \param texture the texture to unbind from the current OpenGL/ES/ES2 + * context. + * \returns 0 on success, or -1 if the operation is not supported. * * \since This function is available since SDL 2.0.0. * @@ -1872,9 +1875,9 @@ extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture); * 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 2.0.8. * @@ -1893,7 +1896,7 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer); * hidden/minimized/offscreen. This 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. * @@ -1906,9 +1909,9 @@ extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * re /** * Toggle VSync of the given renderer. * - * \param renderer The renderer to toggle - * \param vsync 1 for on, 0 for off. All other values are reserved - * \returns a 0 int on success, or non-zero on failure + * \param renderer The renderer to toggle. + * \param vsync 1 for on, 0 for off. All other values are reserved. + * \returns a 0 int on success, or non-zero on failure. * * \since This function is available since SDL 2.0.18. */ diff --git a/include/SDL_rwops.h b/include/SDL_rwops.h index 1abbb138fb..e6db42324d 100644 --- a/include/SDL_rwops.h +++ b/include/SDL_rwops.h @@ -188,7 +188,7 @@ typedef struct SDL_RWops * * Closing the SDL_RWops will close the file handle SDL is holding internally. * - * \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_RWops structure that is created, or NULL on @@ -226,10 +226,10 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(FILE * fp, SDL_bool autoclose); * `FILE*`, depending on what system headers are available to SDL. It is * always intended to be the `FILE*` type from the C runtime's stdio.h. * - * \param fp the `FILE*` that feeds the SDL_RWops stream + * \param fp the `FILE*` that feeds the SDL_RWops stream. * \param autoclose SDL_TRUE to close the `FILE*` when closing the SDL_RWops, * SDL_FALSE to leave the `FILE*` open when the RWops is - * closed + * closed. * \returns a pointer to the SDL_RWops structure that is created, or NULL on * failure; call SDL_GetError() for more information. * @@ -262,8 +262,8 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromFP(void * fp, * If you need to make sure the RWops never writes to the memory buffer, you * should use SDL_RWFromConstMem() with a read-only buffer of memory instead. * - * \param mem a pointer to a buffer to feed an SDL_RWops stream - * \param size the buffer size, in bytes + * \param mem a pointer to a buffer to feed an SDL_RWops stream. + * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call * SDL_GetError() for more information. * @@ -297,8 +297,8 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_RWFromMem(void *mem, int size); * If you need to write to a memory buffer, you should use SDL_RWFromMem() * with a writable buffer of memory instead. * - * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream - * \param size the buffer size, in bytes + * \param mem a pointer to a read-only buffer to feed an SDL_RWops stream. + * \param size the buffer size, in bytes. * \returns a pointer to a new SDL_RWops structure, or NULL if it fails; call * SDL_GetError() for more information. * @@ -360,7 +360,7 @@ extern DECLSPEC SDL_RWops *SDLCALL SDL_AllocRW(void); * creation of the SDL_RWops is not freed by SDL_FreeRW(); the programmer must * be responsible for managing that memory in their **close** method. * - * \param area the SDL_RWops structure to be freed + * \param area the SDL_RWops structure to be freed. * * \since This function is available since SDL 2.0.0. * @@ -378,7 +378,7 @@ extern DECLSPEC void SDLCALL SDL_FreeRW(SDL_RWops * area); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context the SDL_RWops to get the size of the data stream from + * \param context the SDL_RWops to get the size of the data stream from. * \returns the size of the data stream in the SDL_RWops on success, -1 if * unknown or a negative error code on failure; call SDL_GetError() * for more information. @@ -405,10 +405,10 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context a pointer to an SDL_RWops structure + * \param context a pointer to an SDL_RWops structure. * \param offset an offset in bytes, relative to **whence** location; can be - * negative - * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END` + * negative. + * \param whence any of `RW_SEEK_SET`, `RW_SEEK_CUR`, `RW_SEEK_END`. * \returns the final offset in the data stream after the seek or -1 on error. * * \since This function is available since SDL 2.0.10. @@ -435,7 +435,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context, * Prior to SDL 2.0.10, this function was a macro. * * \param context a SDL_RWops data stream object from which to get the current - * offset + * offset. * \returns the current offset in the stream, or -1 if the information can not * be determined. * @@ -465,10 +465,10 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context); * * Prior to SDL 2.0.10, this function was a macro. * - * \param context a pointer to an SDL_RWops structure - * \param ptr a pointer to a buffer to read data into - * \param size the size of each object to read, in bytes - * \param maxnum the maximum number of objects to be read + * \param context a pointer to an SDL_RWops structure. + * \param ptr a pointer to a buffer to read data into. + * \param size the size of each object to read, in bytes. + * \param maxnum the maximum number of objects to be read. * \returns the number of objects read, or 0 at error or end of file; call * SDL_GetError() for more information. * @@ -499,10 +499,10 @@ extern DECLSPEC size_t SDLCALL SDL_RWread(SDL_RWops *context, * * Prior to SDL 2.0.10, this function was a macro. * - * \param context a pointer to an SDL_RWops structure - * \param ptr a pointer to a buffer containing data to write - * \param size the size of an object to write, in bytes - * \param num the number of objects to write + * \param context a pointer to an SDL_RWops structure. + * \param ptr a pointer to a buffer containing data to write. + * \param size the size of an object to write, in bytes. + * \param num the number of objects to write. * \returns the number of objects written, which will be less than **num** on * error; call SDL_GetError() for more information. * @@ -533,7 +533,7 @@ extern DECLSPEC size_t SDLCALL SDL_RWwrite(SDL_RWops *context, * * Prior to SDL 2.0.10, this function was a macro. * - * \param context SDL_RWops structure to close + * \param context SDL_RWops structure to close. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -558,9 +558,9 @@ extern DECLSPEC int SDLCALL SDL_RWclose(SDL_RWops *context); * * The data should be freed with SDL_free(). * - * \param src the SDL_RWops to read all available data from - * \param datasize if not NULL, will store the number of bytes read - * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning + * \param src the SDL_RWops to read all available data from. + * \param datasize if not NULL, will store the number of bytes read. + * \param freesrc if non-zero, calls SDL_RWclose() on `src` before returning. * \returns the data, or NULL if there was an error. * * \since This function is available since SDL 2.0.6. @@ -581,8 +581,8 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile_RW(SDL_RWops *src, * Prior to SDL 2.0.10, this function was a macro wrapping around * SDL_LoadFile_RW. * - * \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 2.0.10. @@ -599,7 +599,7 @@ extern DECLSPEC void *SDLCALL SDL_LoadFile(const char *file, size_t *datasize); /** * Use this function to read a byte from an SDL_RWops. * - * \param src the SDL_RWops to read from + * \param src the SDL_RWops to read from. * \returns the read byte on success or 0 on failure; call SDL_GetError() for * more information. * @@ -616,7 +616,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_ReadU8(SDL_RWops * src); * 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 src the stream from which to read data. * \returns 16 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -632,7 +632,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_ReadLE16(SDL_RWops * src); * 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 src the stream from which to read data. * \returns 16 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -648,7 +648,7 @@ extern DECLSPEC Uint16 SDLCALL SDL_ReadBE16(SDL_RWops * src); * 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 src the stream from which to read data. * \returns 32 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -664,7 +664,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_ReadLE32(SDL_RWops * src); * 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 src the stream from which to read data. * \returns 32 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -680,7 +680,7 @@ extern DECLSPEC Uint32 SDLCALL SDL_ReadBE32(SDL_RWops * src); * 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 src the stream from which to read data. * \returns 64 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -696,7 +696,7 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadLE64(SDL_RWops * src); * 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 src the stream from which to read data. * \returns 64 bits of data in the native byte order of the platform. * * \since This function is available since SDL 2.0.0. @@ -716,8 +716,8 @@ extern DECLSPEC Uint64 SDLCALL SDL_ReadBE64(SDL_RWops * src); /** * Use this function to write a byte to an SDL_RWops. * - * \param dst the SDL_RWops to write to - * \param value the byte value to write + * \param dst the SDL_RWops to write to. + * \param value the byte value to write. * \returns 1 on success or 0 on failure; call SDL_GetError() for more * information. * @@ -735,8 +735,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteU8(SDL_RWops * dst, Uint8 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 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -752,8 +752,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE16(SDL_RWops * dst, Uint16 value); * 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 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -770,8 +770,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteBE16(SDL_RWops * dst, Uint16 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 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -787,8 +787,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE32(SDL_RWops * dst, Uint32 value); * 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 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -805,8 +805,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteBE32(SDL_RWops * dst, Uint32 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 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. @@ -822,8 +822,8 @@ extern DECLSPEC size_t SDLCALL SDL_WriteLE64(SDL_RWops * dst, Uint64 value); * 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 1 on successful write, 0 on error. * * \since This function is available since SDL 2.0.0. diff --git a/include/SDL_sensor.h b/include/SDL_sensor.h index 564a6fe7d2..d872eeb7a4 100644 --- a/include/SDL_sensor.h +++ b/include/SDL_sensor.h @@ -162,7 +162,7 @@ extern DECLSPEC int SDLCALL SDL_NumSensors(void); /** * Get the implementation dependent name of a sensor. * - * \param device_index The sensor to obtain name from + * \param device_index The sensor to obtain name from. * \returns the sensor name, or NULL if `device_index` is out of range. * * \since This function is available since SDL 2.0.9. @@ -172,7 +172,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetDeviceName(int device_index); /** * Get the type of a sensor. * - * \param device_index The sensor to get the type from + * \param device_index The sensor to get the type from. * \returns the SDL_SensorType, or `SDL_SENSOR_INVALID` if `device_index` is * out of range. * @@ -183,7 +183,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetDeviceType(int device_index) /** * Get the platform dependent type of a sensor. * - * \param device_index The sensor to check + * \param device_index The sensor to check. * \returns the sensor platform dependent type, or -1 if `device_index` is out * of range. * @@ -194,7 +194,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDeviceNonPortableType(int device_index) /** * Get the instance ID of a sensor. * - * \param device_index The sensor to get instance id from + * \param device_index The sensor to get instance id from. * \returns the sensor instance ID, or -1 if `device_index` is out of range. * * \since This function is available since SDL 2.0.9. @@ -204,7 +204,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetDeviceInstanceID(int device_in /** * Open a sensor for use. * - * \param device_index The sensor to open + * \param device_index The sensor to open. * \returns an SDL_Sensor sensor object, or NULL if an error occurred. * * \since This function is available since SDL 2.0.9. @@ -214,7 +214,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorOpen(int device_index); /** * Return the SDL_Sensor associated with an instance id. * - * \param instance_id The sensor from instance id + * \param instance_id The sensor from instance id. * \returns an SDL_Sensor object. * * \since This function is available since SDL 2.0.9. @@ -224,7 +224,7 @@ extern DECLSPEC SDL_Sensor *SDLCALL SDL_SensorFromInstanceID(SDL_SensorID instan /** * Get the implementation dependent name of a sensor * - * \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 2.0.9. @@ -234,7 +234,7 @@ extern DECLSPEC const char *SDLCALL SDL_SensorGetName(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. * @@ -245,7 +245,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_SensorGetType(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 2.0.9. @@ -255,7 +255,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetNonPortableType(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 -1 if `sensor` is NULL. * * \since This function is available since SDL 2.0.9. @@ -267,9 +267,9 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_SensorGetInstanceID(SDL_Sensor *sensor) * * 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 or -1 if an error occurred. * * \since This function is available since SDL 2.0.9. @@ -282,11 +282,11 @@ extern DECLSPEC int SDLCALL SDL_SensorGetData(SDL_Sensor *sensor, float *data, i * * The number of values and interpretation of the data is sensor dependent. * - * \param sensor The SDL_Sensor object to query + * \param sensor The SDL_Sensor object to query. * \param timestamp A pointer filled with the timestamp in microseconds of the - * current sensor reading if available, or 0 if not - * \param data A pointer filled with the current sensor state - * \param num_values The number of values to write to data + * current sensor reading if available, or 0 if not. + * \param data A pointer filled with the current sensor state. + * \param num_values The number of values to write to data. * \returns 0 or -1 if an error occurred. * * \since This function is available since SDL 2.26.0. @@ -296,7 +296,7 @@ extern DECLSPEC int SDLCALL SDL_SensorGetDataWithTimestamp(SDL_Sensor *sensor, U /** * Close a sensor previously opened with SDL_SensorOpen(). * - * \param sensor The SDL_Sensor object to close + * \param sensor The SDL_Sensor object to close. * * \since This function is available since SDL 2.0.9. */ diff --git a/include/SDL_surface.h b/include/SDL_surface.h index ad72bf7402..9123422b4f 100644 --- a/include/SDL_surface.h +++ b/include/SDL_surface.h @@ -140,14 +140,14 @@ typedef enum SDL_YUV_CONVERSION_MODE * You can change this by calling SDL_SetSurfaceBlendMode() and selecting a * different `blendMode`. * - * \param flags the flags are unused and should be set to 0 - * \param width the width of the surface - * \param height the height of the surface - * \param depth the depth of the surface in bits - * \param Rmask the red mask for the pixels - * \param Gmask the green mask for the pixels - * \param Bmask the blue mask for the pixels - * \param Amask the alpha mask for the pixels + * \param flags the flags are unused and should be set to 0. + * \param width the width of the surface. + * \param height the height of the surface. + * \param depth the depth of the surface in bits. + * \param Rmask the red mask for the pixels. + * \param Gmask the green mask for the pixels. + * \param Bmask the blue mask for the pixels. + * \param Amask the alpha mask for the pixels. * \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 DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface * of providing pixel color masks, you provide it with a predefined format * from SDL_PixelFormatEnum. * - * \param flags the flags are unused and should be set to 0 - * \param width the width of the surface - * \param height the height of the surface - * \param depth the depth of the surface in bits + * \param flags the flags are unused and should be set to 0. + * \param width the width of the surface. + * \param height the height of the surface. + * \param depth the depth of the surface in bits. * \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. @@ -198,15 +198,15 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceWithFormat * No copy is made of the pixel data. Pixel data is not managed automatically; * you must free the surface before you free the pixel data. * - * \param pixels a pointer to existing pixel data - * \param width the width of the surface - * \param height the height of the surface - * \param depth the depth of the surface in bits - * \param pitch the pitch of the surface in bytes - * \param Rmask the red mask for the pixels - * \param Gmask the green mask for the pixels - * \param Bmask the blue mask for the pixels - * \param Amask the alpha mask for the pixels + * \param pixels a pointer to existing pixel data. + * \param width the width of the surface. + * \param height the height of the surface. + * \param depth the depth of the surface in bits. + * \param pitch the pitch of the surface in bytes. + * \param Rmask the red mask for the pixels. + * \param Gmask the green mask for the pixels. + * \param Bmask the blue mask for the pixels. + * \param Amask the alpha mask for the pixels. * \returns the new SDL_Surface structure that is created or NULL if it fails; * call SDL_GetError() for more information. * @@ -240,11 +240,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels, * No copy is made of the pixel data. Pixel data is not managed automatically; * you must free the surface before you free the pixel data. * - * \param pixels a pointer to existing pixel data - * \param width the width of the surface - * \param height the height of the surface - * \param depth the depth of the surface in bits - * \param pitch the pitch of the surface in bytes + * \param pixels a pointer to existing pixel data. + * \param width the width of the surface. + * \param height the height of the surface. + * \param depth the depth of the surface in bits. + * \param pitch the pitch of the surface in bytes. * \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. @@ -279,8 +279,8 @@ extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); * * 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. * @@ -301,7 +301,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, * 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. * @@ -315,7 +315,7 @@ extern 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 2.0.0. * @@ -333,8 +333,8 @@ extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface * surface); * Alternitavely, you might also use the macro SDL_LoadBMP to load a bitmap * from a file, convert it to an SDL_Surface and then close the file. * - * \param src the data stream for the surface - * \param freesrc non-zero to close the stream after being read + * \param src the data stream for the surface. + * \param freesrc non-zero to close the stream after being read. * \returns a pointer to a new SDL_Surface structure or NULL if there was an * error; call SDL_GetError() for more information. * @@ -364,9 +364,9 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, * 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 freedst non-zero to close the stream after being written + * \param surface the SDL_Surface structure containing the image to be saved. + * \param dst a data stream to save to. + * \param freedst non-zero to close the stream after being written. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -392,8 +392,8 @@ extern DECLSPEC int SDLCALL SDL_SaveBMP_RW * 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. * @@ -411,7 +411,7 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceRLE(SDL_Surface * surface, * * 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 2.0.14. @@ -433,9 +433,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasSurfaceRLE(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. * @@ -452,7 +452,7 @@ extern DECLSPEC int SDLCALL SDL_SetColorKey(SDL_Surface * surface, * * 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. * \return SDL_TRUE if the surface has a color key, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.9. @@ -470,8 +470,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasColorKey(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. * @@ -492,10 +492,10 @@ extern DECLSPEC int SDLCALL SDL_GetColorKey(SDL_Surface * surface, * * `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. * @@ -511,10 +511,10 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceColorMod(SDL_Surface * surface, /** * 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. * @@ -535,8 +535,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceColorMod(SDL_Surface * surface, * * `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. * @@ -551,8 +551,8 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceAlphaMod(SDL_Surface * surface, /** * 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. * @@ -571,8 +571,8 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceAlphaMod(SDL_Surface * surface, * 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. * @@ -586,8 +586,8 @@ extern DECLSPEC int SDLCALL SDL_SetSurfaceBlendMode(SDL_Surface * surface, /** * 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. * @@ -607,9 +607,9 @@ extern DECLSPEC int SDLCALL SDL_GetSurfaceBlendMode(SDL_Surface * surface, * 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. * @@ -628,9 +628,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(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. * * \since This function is available since SDL 2.0.0. * @@ -659,11 +659,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface * surface) * surface. The new, optimized surface can then be used as the source for * future blits, making them faster. * - * \param src the existing SDL_Surface structure to convert + * \param src the existing SDL_Surface structure to convert. * \param fmt the SDL_PixelFormat structure that the new surface is optimized - * for + * for. * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API + * leftover from SDL 1.2's API. * \returns the new SDL_Surface structure that is created or NULL if it fails; * call SDL_GetError() for more information. * @@ -684,11 +684,11 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface * 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 src the existing SDL_Surface structure to convert + * \param src the existing SDL_Surface structure to convert. * \param pixel_format the SDL_PixelFormatEnum that the new surface is - * optimized for + * optimized for. * \param flags the flags are unused and should be set to 0; this is a - * leftover from SDL 1.2's API + * leftover from SDL 1.2's API. * \returns the new SDL_Surface structure that is created or NULL if it fails; * call SDL_GetError() for more information. * @@ -704,14 +704,14 @@ extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurfaceFormat /** * 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. * @@ -730,14 +730,14 @@ extern DECLSPEC int SDLCALL SDL_ConvertPixels(int width, int height, * * 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. * @@ -761,10 +761,10 @@ extern DECLSPEC int SDLCALL SDL_PremultiplyAlpha(int width, int height, * SDL_SetClipRect()), 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. * @@ -787,10 +787,10 @@ extern DECLSPEC int SDLCALL SDL_FillRect * SDL_SetClipRect()), 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_Rect 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. * @@ -886,12 +886,12 @@ extern DECLSPEC int SDLCALL SDL_UpperBlit * Unless you know what you're doing, you should be using SDL_BlitSurface() * instead. * - * \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 rectangle that is - * copied into + * copied into. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -951,12 +951,12 @@ extern DECLSPEC int SDLCALL SDL_UpperBlitScaled * 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 rectangle that is - * copied into + * copied into. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/include/SDL_system.h b/include/SDL_system.h index 5224f908d6..ea47997014 100644 --- a/include/SDL_system.h +++ b/include/SDL_system.h @@ -49,7 +49,7 @@ typedef void (SDLCALL * SDL_WindowsMessageHook)(void *userdata, void *hWnd, unsi * Set a callback for every Windows message, run before TranslateMessage(). * * \param callback The SDL_WindowsMessageHook function to call. - * \param userdata a pointer to pass to every iteration of `callback` + * \param userdata a pointer to pass to every iteration of `callback`. * * \since This function is available since SDL 2.0.4. */ @@ -66,7 +66,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowsMessageHook(SDL_WindowsMessageHook ca * controls on which monitor a full screen application will appear. * * \param displayIndex the display index for which to get the D3D9 adapter - * index + * index. * \returns the D3D9 adapter index on success or a negative error code on * failure; call SDL_GetError() for more information. * @@ -82,7 +82,7 @@ typedef struct IDirect3DDevice9 IDirect3DDevice9; * Once you are done using the device, you should release it to avoid a * resource leak. * - * \param renderer the renderer from which to get the associated D3D device + * \param renderer the renderer from which to get the associated D3D device. * \returns the D3D9 device associated with given renderer or NULL if it is * not a D3D9 renderer; call SDL_GetError() for more information. * @@ -98,7 +98,7 @@ typedef struct ID3D11Device ID3D11Device; * Once you are done using the device, you should release it to avoid a * resource leak. * - * \param renderer the renderer from which to get the associated D3D11 device + * \param renderer the renderer from which to get the associated D3D11 device. * \returns the D3D11 device associated with given renderer or NULL if it is * not a D3D11 renderer; call SDL_GetError() for more information. * @@ -118,7 +118,7 @@ typedef struct ID3D12Device ID3D12Device; * Once you are done using the device, you should release it to avoid a * resource leak. * - * \param renderer the renderer from which to get the associated D3D12 device + * \param renderer the renderer from which to get the associated D3D12 device. * \returns the D3D12 device associated with given renderer or NULL if it is * not a D3D12 renderer; call SDL_GetError() for more information. * @@ -140,9 +140,9 @@ extern DECLSPEC ID3D12Device* SDLCALL SDL_RenderGetD3D12Device(SDL_Renderer* ren * Before SDL 2.0.4 this function did not return a value. Since SDL 2.0.4 it * returns an SDL_bool. * - * \param displayIndex the display index for which to get both indices - * \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 displayIndex the display index for which to get both indices. + * \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. * @@ -176,7 +176,7 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio * \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...) + * SCHED_OTHER, etc...). * \returns 0 on success, or -1 on error. * * \since This function is available since SDL 2.0.18. @@ -210,9 +210,9 @@ typedef void (SDLCALL *SDL_iOSAnimationCallback)(void*); * This functions is also accessible using the macro * SDL_iOSSetAnimationCallback() since SDL 2.0.4. * - * \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 @@ -235,7 +235,7 @@ extern DECLSPEC int SDLCALL SDL_iPhoneSetAnimationCallback(SDL_Window * window, * This functions is also accessible using the macro SDL_iOSSetEventPump() * since SDL 2.0.4. * - * \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 2.0.0. * @@ -445,11 +445,11 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permis * * 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 if success, -1 if any error occurs. * * \since This function is available since SDL 2.0.16. @@ -461,8 +461,8 @@ extern DECLSPEC int SDLCALL SDL_AndroidShowToast(const char* message, int durati * * 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. * * \since This function is available since SDL 2.0.22. */ @@ -528,7 +528,7 @@ typedef enum SDL_WinRT_DeviceFamily * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * \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 UCS-2 string (16-bit, wide-char) containing the path, or NULL if * the path is not available for any reason; call SDL_GetError() for * more information. @@ -551,7 +551,7 @@ extern DECLSPEC const wchar_t * SDLCALL SDL_WinRTGetFSPathUNICODE(SDL_WinRT_Path * * https://msdn.microsoft.com/en-us/library/windows/apps/hh464917.aspx * - * \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/SDL_syswm.h b/include/SDL_syswm.h index 7081adefec..682bf49dcc 100644 --- a/include/SDL_syswm.h +++ b/include/SDL_syswm.h @@ -363,8 +363,8 @@ typedef struct SDL_SysWMinfo SDL_SysWMinfo; * `SDL_VERSION(&info.version)`, and then this function will fill in the rest * of the structure with information about the given window. * - * \param window the window about which information is being requested - * \param info an SDL_SysWMinfo structure filled in with window information + * \param window the window about which information is being requested. + * \param info an SDL_SysWMinfo structure filled in with window information. * \returns SDL_TRUE if the function is implemented and the `version` member * of the `info` struct is valid, or SDL_FALSE if the information * could not be retrieved; call SDL_GetError() for more information. diff --git a/include/SDL_thread.h b/include/SDL_thread.h index 8ad099d464..51c669ed1f 100644 --- a/include/SDL_thread.h +++ b/include/SDL_thread.h @@ -84,7 +84,7 @@ typedef enum SDL_ThreadPriority { /** * The function passed to SDL_CreateThread(). * - * \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(). */ typedef int (SDLCALL * SDL_ThreadFunction) (void *data); @@ -194,9 +194,9 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz * SDL_CreateThreadWithStackSize(fn, name, 0, data); * ``` * - * \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. @@ -240,10 +240,10 @@ SDL_CreateThread(SDL_ThreadFunction fn, const char *name, void *data); * function, but for backwards compatibility, this is currently a separate * function. * - * \param fn the SDL_ThreadFunction function to call in the new thread - * \param name the name of the thread + * \param fn the SDL_ThreadFunction function to call in the new thread. + * \param name the name of the thread. * \param stacksize the size, in bytes, to allocate for the new thread stack. - * \param data a pointer that is passed to `fn` + * \param data a pointer that is passed to `fn`. * \returns an opaque pointer to the new thread object on success, NULL if the * new thread could not be created; call SDL_GetError() for more * information. @@ -263,7 +263,7 @@ SDL_CreateThreadWithStackSize(SDL_ThreadFunction fn, const char *name, const siz * This is internal memory, not to be freed by the caller, and remains valid * until the specified thread is cleaned up by SDL_WaitThread(). * - * \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. * @@ -298,7 +298,7 @@ extern DECLSPEC SDL_threadID SDLCALL SDL_ThreadID(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. * @@ -315,7 +315,7 @@ extern 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. * @@ -346,7 +346,7 @@ extern DECLSPEC int SDLCALL SDL_SetThreadPriority(SDL_ThreadPriority priority); * 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. @@ -385,7 +385,7 @@ extern 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 2.0.2. * @@ -412,7 +412,7 @@ extern DECLSPEC SDL_TLSID SDLCALL SDL_TLSCreate(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. * @@ -436,10 +436,10 @@ typedef void (SDLCALL *SDL_TLSDestructorCallback)(void*); * * where its parameter `value` is what was passed as `value` to SDL_TLSSet(). * - * \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 + * value. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * diff --git a/include/SDL_timer.h b/include/SDL_timer.h index 5e962e1d14..dcba7629e4 100644 --- a/include/SDL_timer.h +++ b/include/SDL_timer.h @@ -140,7 +140,7 @@ extern 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 2.0.0. */ @@ -182,10 +182,10 @@ typedef int SDL_TimerID; * time with SDL_GetTicks() 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 param a pointer that is passed to `callback` + * `interval` elapses. + * \param param a pointer that is passed to `callback`. * \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more * information. * @@ -200,7 +200,7 @@ extern DECLSPEC SDL_TimerID SDLCALL SDL_AddTimer(Uint32 interval, /** * 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 SDL_TRUE if the timer is removed or SDL_FALSE if the timer wasn't * found. * diff --git a/include/SDL_touch.h b/include/SDL_touch.h index f4b0b66564..3c6c4b725c 100644 --- a/include/SDL_touch.h +++ b/include/SDL_touch.h @@ -85,7 +85,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumTouchDevices(void); /** * Get the touch ID with the given index. * - * \param index the touch device index + * \param index the touch device index. * \returns the touch ID with the given index on success or 0 if the index is * invalid; call SDL_GetError() for more information. * @@ -113,7 +113,7 @@ extern DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_TouchID t /** * Get the number of active fingers for a given touch device. * - * \param touchID the ID of a touch device + * \param touchID the ID of a touch device. * \returns the number of active fingers for a given touch device on success * or 0 on failure; call SDL_GetError() for more information. * @@ -128,8 +128,8 @@ extern DECLSPEC int SDLCALL SDL_GetNumTouchFingers(SDL_TouchID touchID); * * The returned resource is owned by SDL and should not be deallocated. * - * \param touchID the ID of the requested touch device - * \param index the index of the requested finger + * \param touchID the ID of the requested touch device. + * \param index the index of the requested finger. * \returns a pointer to the SDL_Finger object or NULL if no object at the * given ID and index could be found. * diff --git a/include/SDL_version.h b/include/SDL_version.h index 120cd15c76..c8b06efb85 100644 --- a/include/SDL_version.h +++ b/include/SDL_version.h @@ -133,7 +133,7 @@ typedef struct SDL_version * * This function may be called safely at any time, even before SDL_Init(). * - * \param ver the SDL_version structure that contains the version information + * \param ver the SDL_version structure that contains the version information. * * \since This function is available since SDL 2.0.0. * diff --git a/include/SDL_video.h b/include/SDL_video.h index 80ed6c1fed..6afc63e65a 100644 --- a/include/SDL_video.h +++ b/include/SDL_video.h @@ -302,7 +302,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); * The video drivers are presented in the order in which they are normally * checked during initialization. * - * \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 2.0.0. @@ -329,7 +329,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); * specific `driver_name`. * * \param driver_name the name of a video driver to initialize, or NULL for - * the default driver + * the default driver. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -382,7 +382,7 @@ extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(void); * Get the name of a display in UTF-8 encoding. * * \param displayIndex the index of display from which the name should be - * queried + * queried. * \returns the name of a display or NULL for an invalid display index or * failure; call SDL_GetError() for more information. * @@ -397,8 +397,8 @@ extern DECLSPEC const char * SDLCALL SDL_GetDisplayName(int displayIndex); * * The primary display (`displayIndex` zero) is always located at 0,0. * - * \param displayIndex the index of the display to query - * \param rect the SDL_Rect structure filled in with the display bounds + * \param displayIndex the index 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. * @@ -427,8 +427,8 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayBounds(int displayIndex, SDL_Rect * re * range. * * \param displayIndex the index of the display to query the usable bounds - * from - * \param rect the SDL_Rect structure filled in with the display bounds + * from. + * \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. * @@ -458,13 +458,13 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayUsableBounds(int displayIndex, SDL_Rec * more consistent, reliable, and clear. * * \param displayIndex the index of the display from which DPI information - * should be queried + * should be queried. * \param ddpi a pointer filled in with the diagonal DPI of the display; may - * be NULL + * be NULL. * \param hdpi a pointer filled in with the horizontal DPI of the display; may - * be NULL + * be NULL. * \param vdpi a pointer filled in with the vertical DPI of the display; may - * be NULL + * be NULL. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -477,7 +477,7 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayDPI(int displayIndex, float * ddpi, fl /** * Get the orientation of a display. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \returns The SDL_DisplayOrientation enum value of the display, or * `SDL_ORIENTATION_UNKNOWN` if it isn't available. * @@ -493,7 +493,7 @@ extern DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetDisplayOrientation(int dis * The `displayIndex` needs to be in the range from 0 to * SDL_GetNumVideoDisplays() - 1. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \returns a number >= 1 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -515,10 +515,10 @@ extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(int displayIndex); * - packed pixel layout -> largest to smallest * - refresh rate -> highest to lowest * - * \param displayIndex the index of the display to query - * \param modeIndex the index of the display mode to query + * \param displayIndex the index of the display to query. + * \param modeIndex the index of the display mode to query. * \param mode an SDL_DisplayMode structure filled in with the mode at - * `modeIndex` + * `modeIndex`. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -537,9 +537,9 @@ extern DECLSPEC int SDLCALL SDL_GetDisplayMode(int displayIndex, int modeIndex, * function will return the previous native display mode, and not the current * display mode. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure filled in with the current display - * mode + * mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -559,9 +559,9 @@ extern DECLSPEC int SDLCALL SDL_GetDesktopDisplayMode(int displayIndex, SDL_Disp * function will return the current display mode, and not the previous native * display mode. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure filled in with the current display - * mode + * mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -585,11 +585,11 @@ extern DECLSPEC int SDLCALL SDL_GetCurrentDisplayMode(int displayIndex, SDL_Disp * and finally checking the refresh rate. If all the available modes are too * small, then NULL is returned. * - * \param displayIndex the index of the display to query + * \param displayIndex the index of the display to query. * \param mode an SDL_DisplayMode structure containing the desired display - * mode + * mode. * \param closest an SDL_DisplayMode structure filled in with the closest - * match of the available display modes + * match of the available display modes. * \returns the passed in value `closest` or NULL if no matching video mode * was available; call SDL_GetError() for more information. * @@ -603,7 +603,7 @@ extern DECLSPEC SDL_DisplayMode * SDLCALL SDL_GetClosestDisplayMode(int displayI /** * Get the index of the display containing a point * - * \param point the point to query + * \param point the point to query. * \returns the index of the display containing the point or a negative error * code on failure; call SDL_GetError() for more information. * @@ -617,7 +617,7 @@ extern DECLSPEC int SDLCALL SDL_GetPointDisplayIndex(const SDL_Point * point); /** * Get the index of the display primarily containing a rect * - * \param rect the rect to query + * \param rect the rect to query. * \returns the index of the display entirely containing the rect or closest * to the center of the rect on success or a negative error code on * failure; call SDL_GetError() for more information. @@ -632,7 +632,7 @@ extern DECLSPEC int SDLCALL SDL_GetRectDisplayIndex(const SDL_Rect * rect); /** * Get the index of the display associated with a window. * - * \param window the window to query + * \param window the window to query. * \returns the index of the display containing the center of the window on * success or a negative error code on failure; call SDL_GetError() * for more information. @@ -651,10 +651,10 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayIndex(SDL_Window * window); * change the window size when the window is not fullscreen, use * SDL_SetWindowSize(). * - * \param window the window to affect + * \param window the window to affect. * \param mode the SDL_DisplayMode structure representing the mode to use, or * NULL to use the window's dimensions and the desktop's format - * and refresh rate + * and refresh rate. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -669,9 +669,9 @@ extern DECLSPEC int SDLCALL SDL_SetWindowDisplayMode(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. * \param mode an SDL_DisplayMode structure filled in with the fullscreen - * display mode + * display mode. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -688,8 +688,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowDisplayMode(SDL_Window * window, * * 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. * @@ -700,7 +700,7 @@ extern DECLSPEC void* SDLCALL SDL_GetWindowICCProfile(SDL_Window * window, size_ /** * 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. @@ -764,14 +764,14 @@ extern 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 title the title of the window, in UTF-8 encoding. * \param x the x position of the window, `SDL_WINDOWPOS_CENTERED`, or - * `SDL_WINDOWPOS_UNDEFINED` + * `SDL_WINDOWPOS_UNDEFINED`. * \param y the y position of the window, `SDL_WINDOWPOS_CENTERED`, or - * `SDL_WINDOWPOS_UNDEFINED` - * \param w the width of the window, in screen coordinates - * \param h the height of the window, in screen coordinates - * \param flags 0, or one or more SDL_WindowFlags OR'd together + * `SDL_WINDOWPOS_UNDEFINED`. + * \param w the width of the window, in screen coordinates. + * \param h the height of the window, in screen coordinates. + * \param flags 0, or one or more SDL_WindowFlags OR'd together. * \returns the `SDL_Window` that was created or NULL on failure; call * SDL_GetError() for more information. * @@ -792,7 +792,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindow(const char *title, * before using SDL_CreateWindowFrom(). * * \param data a pointer to driver-dependent window creation data, typically - * your native window cast to a void* + * your native window cast to a void*. * \returns the window that was created or NULL on failure; call * SDL_GetError() for more information. * @@ -809,7 +809,7 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_CreateWindowFrom(const void *data); * 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. * @@ -825,7 +825,7 @@ extern DECLSPEC Uint32 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. * @@ -838,8 +838,8 @@ extern DECLSPEC SDL_Window * SDLCALL SDL_GetWindowFromID(Uint32 id); /** * 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 2.0.0. * @@ -858,8 +858,8 @@ extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_Window * window); * * 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. * * \since This function is available since SDL 2.0.0. * @@ -871,7 +871,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_Window * window, /** * Get the title of a window. * - * \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. * @@ -884,8 +884,8 @@ extern 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. * * \since This function is available since SDL 2.0.0. */ @@ -897,9 +897,9 @@ extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Window * window, * * `name` is case-sensitive. * - * \param window the window to associate with the pointer - * \param name the name of the pointer - * \param userdata the associated pointer + * \param window the window to associate with the pointer. + * \param name the name of the pointer. + * \param userdata the associated pointer. * \returns the previous value associated with `name`. * * \since This function is available since SDL 2.0.0. @@ -913,8 +913,8 @@ extern DECLSPEC void* SDLCALL SDL_SetWindowData(SDL_Window * window, /** * Retrieve the data pointer associated with a window. * - * \param window the window to query - * \param name the name of the pointer + * \param window the window to query. + * \param name the name of the pointer. * \returns the value associated with `name`. * * \since This function is available since SDL 2.0.0. @@ -929,11 +929,11 @@ extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_Window * window, * * The window coordinate origin is the upper left of the display. * - * \param window the window to reposition + * \param window the window to reposition. * \param x the x coordinate of the window in screen coordinates, or - * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED` + * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`. * \param y the y coordinate of the window in screen coordinates, or - * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED` + * `SDL_WINDOWPOS_CENTERED` or `SDL_WINDOWPOS_UNDEFINED`. * * \since This function is available since SDL 2.0.0. * @@ -948,11 +948,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_Window * window, * 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 window the window to query. * \param x a pointer filled in with the x position of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * \param y a pointer filled in with the y position of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * * \since This function is available since SDL 2.0.0. * @@ -972,11 +972,11 @@ extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_Window * window, * Fullscreen windows automatically match the size of the display mode, and * you should use SDL_SetWindowDisplayMode() to change their size. * - * \param window the window to change + * \param window the window to change. * \param w the width of the window in pixels, in screen coordinates, must be - * > 0 + * > 0. * \param h the height of the window in pixels, in screen coordinates, must be - * > 0 + * > 0. * * \since This function is available since SDL 2.0.0. * @@ -998,11 +998,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_Window * window, int w, * SDL_Vulkan_GetDrawableSize(), or SDL_GetRendererOutputSize() to get the * real client area size in pixels. * - * \param window the window to query the width and height from + * \param window the window to query the width and height from. * \param w a pointer filled in with the width of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * \param h a pointer filled in with the height of the window, in screen - * coordinates, may be NULL + * coordinates, may be NULL. * * \since This function is available since SDL 2.0.0. * @@ -1029,15 +1029,15 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_Window * window, int *w, * 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. * @@ -1057,10 +1057,11 @@ extern DECLSPEC int SDLCALL SDL_GetWindowBordersSize(SDL_Window * window, * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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. * * \since This function is available since SDL 2.26.0. * @@ -1073,9 +1074,9 @@ extern DECLSPEC void SDLCALL SDL_GetWindowSizeInPixels(SDL_Window * window, /** * 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 in pixels - * \param min_h the minimum height of the window in pixels + * \param window the window to change. + * \param min_w the minimum width of the window in pixels. + * \param min_h the minimum height of the window in pixels. * * \since This function is available since SDL 2.0.0. * @@ -1088,11 +1089,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMinimumSize(SDL_Window * window, /** * 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. * * \since This function is available since SDL 2.0.0. * @@ -1105,9 +1106,9 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMinimumSize(SDL_Window * window, /** * 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 in pixels - * \param max_h the maximum height of the window in pixels + * \param window the window to change. + * \param max_w the maximum width of the window in pixels. + * \param max_h the maximum height of the window in pixels. * * \since This function is available since SDL 2.0.0. * @@ -1120,11 +1121,11 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMaximumSize(SDL_Window * window, /** * 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. * * \since This function is available since SDL 2.0.0. * @@ -1143,8 +1144,8 @@ extern DECLSPEC void SDLCALL SDL_GetWindowMaximumSize(SDL_Window * window, * * 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. * * \since This function is available since SDL 2.0.0. * @@ -1162,8 +1163,8 @@ extern DECLSPEC void SDLCALL SDL_SetWindowBordered(SDL_Window * window, * * 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. * * \since This function is available since SDL 2.0.5. * @@ -1178,9 +1179,9 @@ extern DECLSPEC void SDLCALL SDL_SetWindowResizable(SDL_Window * window, * 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. * * \since This function is available since SDL 2.0.16. * @@ -1192,7 +1193,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowAlwaysOnTop(SDL_Window * window, /** * Show a window. * - * \param window the window to show + * \param window the window to show. * * \since This function is available since SDL 2.0.0. * @@ -1204,7 +1205,7 @@ extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_Window * window); /** * Hide a window. * - * \param window the window to hide + * \param window the window to hide. * * \since This function is available since SDL 2.0.0. * @@ -1215,7 +1216,7 @@ extern DECLSPEC void 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. * * \since This function is available since SDL 2.0.0. */ @@ -1224,7 +1225,7 @@ extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_Window * window); /** * Make a window as large as possible. * - * \param window the window to maximize + * \param window the window to maximize. * * \since This function is available since SDL 2.0.0. * @@ -1236,7 +1237,7 @@ extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_Window * window); /** * Minimize a window to an iconic representation. * - * \param window the window to minimize + * \param window the window to minimize. * * \since This function is available since SDL 2.0.0. * @@ -1248,7 +1249,7 @@ extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_Window * window); /** * Restore the size and position of a minimized or maximized window. * - * \param window the window to restore + * \param window the window to restore. * * \since This function is available since SDL 2.0.0. * @@ -1268,8 +1269,8 @@ extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_Window * window); * SDL_RENDER_TARGETS_RESET event. Your application should be prepared to * handle this event by reuploading textures! * - * \param window the window to change - * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0 + * \param window the window to change. + * \param flags `SDL_WINDOW_FULLSCREEN`, `SDL_WINDOW_FULLSCREEN_DESKTOP` or 0. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1311,7 +1312,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_HasWindowSurface(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. * @@ -1332,7 +1333,7 @@ extern DECLSPEC SDL_Surface * SDLCALL SDL_GetWindowSurface(SDL_Window * window); * * 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. * @@ -1356,10 +1357,10 @@ extern 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. * @@ -1375,7 +1376,7 @@ extern 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. * @@ -1396,8 +1397,8 @@ extern 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 input grab mode should be set - * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input + * \param window the window for which the input grab mode should be set. + * \param grabbed SDL_TRUE to grab input or SDL_FALSE to release input. * * \since This function is available since SDL 2.0.0. * @@ -1458,7 +1459,7 @@ extern DECLSPEC void SDLCALL SDL_SetWindowMouseGrab(SDL_Window * window, /** * Get a window's input grab mode. * - * \param window the window to query + * \param window the window to query. * \returns SDL_TRUE if input is grabbed, SDL_FALSE otherwise. * * \since This function is available since SDL 2.0.0. @@ -1470,7 +1471,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowGrab(SDL_Window * window); /** * 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 2.0.16. @@ -1483,7 +1484,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowKeyboardGrab(SDL_Window * window); /** * 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 2.0.16. @@ -1527,7 +1528,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowMouseRect(SDL_Window * window, const SD /** * 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. * @@ -1552,9 +1553,9 @@ extern DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window * win * something similar. * * \param window the window used to select the display whose brightness will - * be changed + * be changed. * \param brightness the brightness (gamma multiplier) value to set where 0.0 - * is completely dark and 1.0 is normal brightness + * is completely dark and 1.0 is normal brightness. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1574,7 +1575,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowBrightness(SDL_Window * window, float b * this display can be retrieved using SDL_GetWindowDisplayIndex().) * * \param window the window used to select the display whose brightness will - * be queried + * be queried. * \returns the brightness for the display where 0.0 is completely dark and * 1.0 is normal brightness. * @@ -1592,8 +1593,8 @@ extern DECLSPEC float SDLCALL SDL_GetWindowBrightness(SDL_Window * window); * * 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. * @@ -1613,8 +1614,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window * window, float opac * * 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. * @@ -1627,8 +1628,8 @@ extern DECLSPEC int SDLCALL SDL_GetWindowOpacity(SDL_Window * window, float * ou /** * Set the window as a modal for another window. * - * \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. * @@ -1643,7 +1644,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowModalFor(SDL_Window * modal_window, SDL * 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. * @@ -1669,13 +1670,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowInputFocus(SDL_Window * window); * ramp set will not follow the window if it is moved to another display. * * \param window the window used to select the display whose gamma ramp will - * be changed + * be changed. * \param red a 256 element array of 16-bit quantities representing the - * translation table for the red channel, or NULL + * translation table for the red channel, or NULL. * \param green a 256 element array of 16-bit quantities representing the - * translation table for the green channel, or NULL + * translation table for the green channel, or NULL. * \param blue a 256 element array of 16-bit quantities representing the - * translation table for the blue channel, or NULL + * translation table for the blue channel, or NULL. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1697,13 +1698,13 @@ extern DECLSPEC int SDLCALL SDL_SetWindowGammaRamp(SDL_Window * window, * this display can be retrieved using SDL_GetWindowDisplayIndex().) * * \param window the window used to select the display whose gamma ramp will - * be queried + * be queried. * \param red a 256 element array of 16-bit quantities filled in with the - * translation table for the red channel, or NULL + * translation table for the red channel, or NULL. * \param green a 256 element array of 16-bit quantities filled in with the - * translation table for the green channel, or NULL + * translation table for the green channel, or NULL. * \param blue a 256 element array of 16-bit quantities filled in with the - * translation table for the blue channel, or NULL + * translation table for the blue channel, or NULL. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1738,9 +1739,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(). * \return an SDL_HitTestResult value. * * \sa SDL_SetWindowHitTest @@ -1781,9 +1782,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 -1 on error (including unsupported); call * SDL_GetError() for more information. * @@ -1796,8 +1797,8 @@ extern DECLSPEC int SDLCALL SDL_SetWindowHitTest(SDL_Window * window, /** * Request a window to demand attention from the user. * - * \param window the window to be flashed - * \param operation the flash operation + * \param window the window to be flashed. + * \param operation the flash operation. * \returns 0 on success or a negative error code on failure; call * SDL_GetError() for more information. * @@ -1811,7 +1812,7 @@ extern DECLSPEC int SDLCALL SDL_FlashWindow(SDL_Window * window, SDL_FlashOperat * 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 2.0.0. * @@ -1882,7 +1883,7 @@ extern DECLSPEC void 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. * @@ -1934,7 +1935,7 @@ extern 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. * @@ -1969,7 +1970,7 @@ extern 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 2.0.0. @@ -1995,8 +1996,9 @@ extern 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. * @@ -2010,8 +2012,9 @@ extern 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. * @@ -2033,7 +2036,7 @@ extern 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. * @@ -2050,8 +2053,8 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_Window * * * 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. * @@ -2094,10 +2097,11 @@ extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_GetCurrentContext(void); * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \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. * * \since This function is available since SDL 2.0.1. * @@ -2126,7 +2130,7 @@ extern DECLSPEC void SDLCALL SDL_GL_GetDrawableSize(SDL_Window * window, int *w, * 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 -1 if setting the swap interval is not supported; * call SDL_GetError() for more information. * @@ -2163,7 +2167,7 @@ extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); * 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. * * \since This function is available since SDL 2.0.0. */ @@ -2172,7 +2176,7 @@ extern DECLSPEC void 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. * * \since This function is available since SDL 2.0.0. * diff --git a/include/SDL_vulkan.h b/include/SDL_vulkan.h index 07adb8d33a..06d8135f93 100644 --- a/include/SDL_vulkan.h +++ b/include/SDL_vulkan.h @@ -97,7 +97,7 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */ * 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 -1 if the library couldn't be loaded; call * SDL_GetError() for more information. * @@ -146,11 +146,11 @@ extern DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void); * however, this parameter will likely be removed in future releases * * \param window A window for which the required Vulkan instance extensions - * should be retrieved (will be deprecated in a future release) + * should be retrieved (will be deprecated in a future release). * \param pCount A pointer to an unsigned int corresponding to the number of - * extensions to be returned + * extensions to be returned. * \param pNames NULL or a pointer to an array to be filled with required - * Vulkan instance extensions + * Vulkan instance extensions. * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available since SDL 2.0.6. @@ -168,10 +168,10 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_GetInstanceExtensions(SDL_Window *wi * `instance` must have been created with extensions returned by * SDL_Vulkan_GetInstanceExtensions() enabled. * - * \param window The window to which to attach the Vulkan surface - * \param instance The Vulkan instance handle + * \param window The window to which to attach the Vulkan surface. + * \param instance The Vulkan instance handle. * \param surface A pointer to a VkSurfaceKHR handle to output the newly - * created surface + * created surface. * \returns SDL_TRUE on success, SDL_FALSE on error. * * \since This function is available since SDL 2.0.6. @@ -191,9 +191,9 @@ extern DECLSPEC SDL_bool SDLCALL SDL_Vulkan_CreateSurface(SDL_Window *window, * platform with high-DPI support (Apple calls this "Retina"), and not * disabled by the `SDL_HINT_VIDEO_HIGHDPI_DISABLED` hint. * - * \param window an SDL_Window for which the size is to be queried - * \param w Pointer to the variable to write the width to or NULL - * \param h Pointer to the variable to write the height to or NULL + * \param window an SDL_Window for which the size is to be queried. + * \param w Pointer to the variable to write the width to or NULL. + * \param h Pointer to the variable to write the height to or NULL. * * \since This function is available since SDL 2.0.6. *