eden-emu/SDL
19
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Sync SDL2 wiki -> header

Browse source
This commit is contained in:
SDL Wiki Bot 2024-06-14 06:11:54 +00:00
parent 169f77ed5e
commit 143d5d779c
41 changed files with 1150 additions and 1138 deletions
Download patch file Download diff file Expand all files Collapse all files

2
include/SDL.h
View file

@ -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.
*

10
include/SDL_assert.h
View file

@ -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.

34
include/SDL_atomic.h
View file

@ -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.

123
include/SDL_audio.h
View file

@ -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.
*

2
include/SDL_bits.h
View file

@ -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

12
include/SDL_blendmode.h
View file

@ -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.
*

4
include/SDL_clipboard.h
View file

@ -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.
*

8
include/SDL_endian.h
View file

@ -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

8
include/SDL_error.h
View file

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

60
include/SDL_events.h
View file

@ -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.
*

4
include/SDL_filesystem.h
View file

@ -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.).

166
include/SDL_gamecontroller.h
View file

@ -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.
*

12
include/SDL_gesture.h
View file

@ -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.
*

8
include/SDL_guid.h
View file

@ -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.

79
include/SDL_haptic.h
View file

@ -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.
*

4
include/SDL_hidapi.h
View file

@ -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.
*/

38
include/SDL_hints.h
View file

@ -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.
*

163
include/SDL_joystick.h
View file

@ -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.
*/

20
include/SDL_keyboard.h
View file

@ -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.

8
include/SDL_loadso.h
View file

@ -55,7 +55,7 @@ extern "C" {
/**
* Dynamically load a shared object.
*
* \param sofile a system-dependent name of the object file
* \param sofile a system-dependent name of the object file.
* \returns an opaque pointer to the object handle or NULL if there was an
* error; call SDL_GetError() for more information.
*
@ -81,8 +81,8 @@ extern 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.
*

81
include/SDL_log.h
View file

@ -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.
*

16
include/SDL_main.h
View file

@ -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.
*

13
include/SDL_messagebox.h
View file

@ -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.
*

6
include/SDL_metal.h
View file

@ -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.
*

46
include/SDL_mouse.h
View file

@ -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.
*

38
include/SDL_mutex.h
View file

@ -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.

94
include/SDL_pixels.h
View file

@ -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.
*

4
include/SDL_power.h
View file

@ -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.

68
include/SDL_rect.h
View file

@ -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.

395
include/SDL_render.h
View file

@ -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<MTLRenderCommandEncoder>` 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.
*/

96
include/SDL_rwops.h
View file

@ -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.

36
include/SDL_sensor.h
View file

@ -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.
*/

200
include/SDL_surface.h
View file

@ -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.
*

40
include/SDL_system.h
View file

@ -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.

4
include/SDL_syswm.h
View file

@ -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.

32
include/SDL_thread.h
View file

@ -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.
*

10
include/SDL_timer.h
View file

@ -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.
*

8
include/SDL_touch.h
View file

@ -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.
*

2
include/SDL_version.h
View file

@ -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.
*

314
include/SDL_video.h
View file

@ -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.
*

20
include/SDL_vulkan.h
View file

@ -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.
*