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

Made return value descriptions more consistent across the API

Browse source
This commit is contained in:
Sam Lantinga 2024-07-18 00:30:33 -07:00
parent d73c7311d5
commit 217330a7b3
24 changed files with 194 additions and 175 deletions
Download patch file Download diff file Expand all files Collapse all files

63
include/SDL3/SDL_audio.h
View file

@ -480,8 +480,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioPlaybackDevices(int *
* \param count a pointer filled in with the number of devices returned. NULL
* is allowed.
* \returns a 0 terminated array of device instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free(), or NULL on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -498,7 +498,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID *SDLCALL SDL_GetAudioRecordingDevices(int
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param devid the instance ID of the device to query.
* \returns the name of the audio device, or NULL on error.
* \returns the name of the audio device, or NULL on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -633,7 +634,7 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioDeviceChannelMap(SDL_AudioDe
* default device.
* \param spec the requested device configuration. Can be NULL to use
* reasonable defaults.
* \returns the device ID on success, 0 on error; call SDL_GetError() for more
* \returns the device ID on success or 0 on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
@ -738,7 +739,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_AudioDevicePaused(SDL_AudioDeviceID dev
* this function will always return -1.0f when used on physical devices.
*
* \param devid the audio device to query.
* \returns the gain of the device, or -1.0f on error.
* \returns the gain of the device or -1.0f on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -771,7 +773,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid
*
* \param devid the audio device on which to change gain.
* \param gain the gain. 1.0f is no change, 0.0f is silence.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -827,8 +830,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID devid);
* \param devid an audio device to bind a stream to.
* \param streams an array of audio streams to unbind.
* \param num_streams number streams listed in the `streams` array.
* \returns 0 on success, -1 on error; call SDL_GetError() for more
* information.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -848,7 +851,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_BindAudioStreams(SDL_AudioDeviceID devid, SD
*
* \param devid an audio device to bind a stream to.
* \param stream an audio stream to bind to a device.
* \returns 0 on success, -1 on error; call SDL_GetError() for more
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
@ -922,7 +925,8 @@ extern SDL_DECLSPEC SDL_AudioDeviceID SDLCALL SDL_GetAudioStreamDevice(SDL_Audio
*
* \param src_spec the format details of the input audio.
* \param dst_spec the format details of the output audio.
* \returns a new audio stream on success, or NULL on failure.
* \returns a new audio stream on success or NULL on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -955,7 +959,8 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetAudioStreamProperties(SDL_Au
* \param stream the SDL_AudioStream to query.
* \param src_spec where to store the input audio format; ignored if NULL.
* \param dst_spec where to store the output audio format; ignored if NULL.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -986,7 +991,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetAudioStreamFormat(SDL_AudioStream *stream
* changed.
* \param dst_spec the new format of the audio output; if NULL, it is not
* changed.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1004,7 +1010,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFormat(SDL_AudioStream *stream
* Get the frequency ratio of an audio stream.
*
* \param stream the SDL_AudioStream to query.
* \returns the frequency ratio of the stream, or 0.0 on error.
* \returns the frequency ratio of the stream or 0.0 on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1030,7 +1037,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamFrequencyRatio(SDL_AudioStre
* \param stream the stream the frequency ratio is being changed.
* \param ratio the frequency ratio. 1.0 is normal speed. Must be between 0.01
* and 100.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1051,7 +1059,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamFrequencyRatio(SDL_AudioStream
* Audio streams default to a gain of 1.0f (no change in output).
*
* \param stream the SDL_AudioStream to query.
* \returns the gain of the stream, or -1.0f on error.
* \returns the gain of the stream or -1.0f on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1075,7 +1084,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioStreamGain(SDL_AudioStream *stream
*
* \param stream the stream on which the gain is being changed.
* \param gain the gain. 1.0f is no change, 0.0f is silence.
* \returns 0 on success, or -1 on error.
* \returns 0 on successor a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running.
@ -1173,7 +1183,8 @@ extern SDL_DECLSPEC const int * SDLCALL SDL_GetAudioStreamOutputChannelMap(SDL_A
* \param stream the SDL_AudioStream to change.
* \param chmap the new channel map, NULL to reset to default.
* \param count The number of channels in the map.
* \returns 0 on success, -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running. Don't change the
@ -1219,7 +1230,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamInputChannelMap(SDL_AudioStrea
* \param stream the SDL_AudioStream to change.
* \param chmap the new channel map, NULL to reset to default.
* \param count The number of channels in the map.
* \returns 0 on success, -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, as it holds
* a stream-specific mutex while running. Don't change the
@ -1277,7 +1289,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *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.
* \returns the number of bytes read from the stream or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread, but if the
* stream has a callback set, the caller might need to manage
@ -1558,7 +1571,8 @@ typedef void (SDLCALL *SDL_AudioStreamCallback)(void *userdata, SDL_AudioStream
* stream.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. This only fails if `stream` is NULL.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1606,7 +1620,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_SetAudioStreamGetCallback(SDL_AudioStream *s
* stream.
* \param userdata an opaque pointer provided to the callback for its own
* personal use.
* \returns 0 on success, -1 on error. This only fails if `stream` is NULL.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information. This only fails if `stream` is NULL.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -1687,7 +1702,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_DestroyAudioStream(SDL_AudioStream *stream)
* necessary.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
* Ignored if callback is NULL.
* \returns an audio stream on success, ready to use. NULL on error; call
* \returns an audio stream on success, ready to use, or NULL on failure; call
* SDL_GetError() for more information. When done with this stream,
* call SDL_DestroyAudioStream to free resources and close the
* device.
@ -1783,8 +1798,8 @@ typedef void (SDLCALL *SDL_AudioPostmixCallback)(void *userdata, const SDL_Audio
* \param devid the ID of an opened audio device.
* \param callback a callback function to be called. Can be NULL.
* \param userdata app-controlled pointer passed to callback. Can be NULL.
* \returns zero on success, -1 on error; call SDL_GetError() for more
* information.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*

12
include/SDL3/SDL_camera.h
View file

@ -173,8 +173,8 @@ extern SDL_DECLSPEC const char *SDLCALL SDL_GetCurrentCameraDriver(void);
* \param count a pointer filled in with the number of camera devices. Can be
* NULL.
* \returns a 0 terminated array of camera instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free() or NULL on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -215,8 +215,8 @@ extern SDL_DECLSPEC SDL_CameraID *SDLCALL SDL_GetCameras(int *count);
* \param count a pointer filled in with the number of elements in the list.
* Can be NULL.
* \returns a 0 terminated array of SDL_CameraSpecs, which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free(), or NULL on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -233,7 +233,7 @@ extern SDL_DECLSPEC SDL_CameraSpec *SDLCALL SDL_GetCameraSupportedFormats(SDL_Ca
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the camera device instance ID.
* \returns a human-readable device name, or NULL on error; call
* \returns a human-readable device name or NULL on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
@ -297,7 +297,7 @@ extern SDL_DECLSPEC SDL_CameraPosition SDLCALL SDL_GetCameraPosition(SDL_CameraI
* \param instance_id the camera device instance ID.
* \param spec the desired format for data the device will provide. Can be
* NULL.
* \returns device, or NULL on failure; call SDL_GetError() for more
* \returns an SDL_Camera object or NULL on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.

2
include/SDL3/SDL_error.h
View file

@ -56,7 +56,7 @@ extern "C" {
* \param fmt a printf()-style message format string.
* \param ... additional parameters matching % tokens in the `fmt` string, if
* any.
* \returns always -1.
* \returns -1.
*
* \since This function is available since SDL 3.0.0.
*

2
include/SDL3/SDL_events.h
View file

@ -1323,7 +1323,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetEventFilter(SDL_EventFilter *filter,
*
* \param filter an SDL_EventFilter function to call when an event happens.
* \param userdata a pointer that is passed to `filter`.
* \returns 0 on success, or a negative error code on failure; call
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.

20
include/SDL3/SDL_gamepad.h
View file

@ -301,7 +301,7 @@ typedef struct SDL_GamepadBinding
*
* \param mapping the mapping string.
* \returns 1 if a new mapping is added, 0 if an existing mapping is updated,
* -1 on error; call SDL_GetError() for more information.
* -1 on failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -332,7 +332,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mapping);
* \param src the data stream for the mappings to be added.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \returns the number of mappings added or -1 on error; call SDL_GetError()
* \returns the number of mappings added or -1 on failure; call SDL_GetError()
* for more information.
*
* \threadsafety It is safe to call this function from any thread.
@ -360,7 +360,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_AddGamepadMappingsFromIO(SDL_IOStream *src,
* Windows, etc).
*
* \param file the mappings file to load.
* \returns the number of mappings added or -1 on error; call SDL_GetError()
* \returns the number of mappings added or -1 on failure; call SDL_GetError()
* for more information.
*
* \threadsafety It is safe to call this function from any thread.
@ -393,8 +393,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReloadGamepadMappings(void);
*
* \param count a pointer filled in with the number of mappings returned, can
* be NULL.
* \returns an array of the mapping strings, NULL-terminated. Returns NULL on
* error; call SDL_GetError() for more information.
* \returns an array of the mapping strings, NULL-terminated, or NULL on
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -406,7 +406,7 @@ extern SDL_DECLSPEC const char * const * SDLCALL SDL_GetGamepadMappings(int *cou
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \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
* \returns a mapping string or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
@ -470,7 +470,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasGamepad(void);
*
* \param count a pointer filled in with the number of gamepads returned.
* \returns a 0 terminated array of joystick instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more details.
*
* \since This function is available since SDL 3.0.0.
@ -971,7 +971,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadConnected(SDL_Gamepad *gamepad);
* SDL to crash.
*
* \param gamepad the gamepad object that you want to get a joystick from.
* \returns an SDL_Joystick object; call SDL_GetError() for more information.
* \returns an SDL_Joystick object, or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -1013,7 +1013,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadEventsEnabled(void);
* \param gamepad a gamepad.
* \param count a pointer filled in with the number of bindings returned.
* \returns a NULL terminated array of pointers to bindings which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more details.
*
* \since This function is available since SDL 3.0.0.
@ -1199,7 +1199,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GamepadHasButton(SDL_Gamepad *gamepad,
*
* \param gamepad a gamepad.
* \param button a button index (one of the SDL_GamepadButton values).
* \returns 1 for pressed state or 0 for not pressed state or error; call
* \returns 1 for pressed state or 0 for not pressed state or failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

4
include/SDL3/SDL_haptic.h
View file

@ -935,8 +935,8 @@ typedef Uint32 SDL_HapticID;
* \param count a pointer filled in with the number of haptic devices
* returned.
* \returns a 0 terminated array of haptic device instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*

30
include/SDL3/SDL_hidapi.h
View file

@ -263,7 +263,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_hid_free_enumeration(SDL_hid_device_info *d
* \param serial_number the Serial Number of the device to open (Optionally
* NULL).
* \returns a pointer to a SDL_hid_device object on success or NULL on
* failure.
* failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -277,7 +278,8 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open(unsigned short vendor_
*
* \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.
* failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -303,7 +305,8 @@ extern SDL_DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path)
* \param data the data to send, including the report number as the first
* byte.
* \param length the length in bytes of the data to send.
* \returns the actual number of bytes written and -1 on error.
* \returns the actual number of bytes written and -1 on on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -322,7 +325,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigne
* reports, make sure to read an extra byte for the report
* number.
* \param milliseconds timeout in milliseconds or -1 for blocking wait.
* \returns the actual number of bytes read and -1 on error. If no packet was
* \returns the actual number of bytes read and -1 on on failure; call
* SDL_GetError() for more information. If no packet was
* available to be read within the timeout period, this function
* returns 0.
*
@ -342,7 +346,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsign
* \param length the number of bytes to read. For devices with multiple
* reports, make sure to read an extra byte for the report
* number.
* \returns the actual number of bytes read and -1 on error. If no packet was
* \returns the actual number of bytes read and -1 on failure; call
* SDL_GetError() for more information. If no packet was
* available to be read and the handle is in non-blocking mode, this
* function returns 0.
*
@ -387,7 +392,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int
* byte.
* \param length the length in bytes of the data to send, including the report
* number.
* \returns the actual number of bytes written and -1 on error.
* \returns the actual number of bytes written and -1 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -409,7 +415,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev,
* \param length the number of bytes to read, including an extra byte for the
* report ID. The buffer can be longer than the actual report.
* \returns the number of bytes read plus one for the report ID (which is
* still in the first byte), or -1 on error.
* still in the first byte), or -1 on on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -431,7 +438,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_feature_report(SDL_hid_device *dev,
* \param length the number of bytes to read, including an extra byte for the
* report ID. The buffer can be longer than the actual report.
* \returns the number of bytes read plus one for the report ID (which is
* still in the first byte), or -1 on error.
* still in the first byte), or -1 on on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -505,8 +513,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_hid_get_indexed_string(SDL_hid_device *dev,
* Get the device info from a HID device.
*
* \param dev a device handle returned from SDL_hid_open().
* \returns a pointer to the SDL_hid_device_info for this hid_device, or NULL
* in the case of failure; call SDL_GetError() for more information.
* \returns a pointer to the SDL_hid_device_info for this hid_device or NULL
* on failure; call SDL_GetError() for more information.
* This struct is valid until the device is closed with
* SDL_hid_close().
*
@ -523,7 +531,7 @@ extern SDL_DECLSPEC SDL_hid_device_info * SDLCALL SDL_hid_get_device_info(SDL_hi
* \param dev a device handle returned from SDL_hid_open().
* \param buf the buffer to copy descriptor into.
* \param buf_size the size of the buffer in bytes.
* \returns the number of bytes actually copied, or -1 on error; call
* \returns the number of bytes actually copied or -1 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

74
include/SDL3/SDL_iostream.h
View file

@ -224,7 +224,7 @@ typedef struct SDL_IOStream SDL_IOStream;
* \param file a UTF-8 string representing the filename to open.
* \param mode an ASCII string representing the mode to be used for opening
* the file.
* \returns a pointer to the SDL_IOStream structure that is created, or NULL
* \returns a pointer to the SDL_IOStream structure that is created or NULL
* on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -258,7 +258,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromFile(const char *file, const
*
* \param mem a pointer to a buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* \returns a pointer to a new SDL_IOStream structure or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -291,7 +291,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromMem(void *mem, size_t size);
*
* \param mem a pointer to a read-only buffer to feed an SDL_IOStream stream.
* \param size the buffer size, in bytes.
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* \returns a pointer to a new SDL_IOStream structure or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -319,7 +319,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromConstMem(const void *mem, si
* - `SDL_PROP_IOSTREAM_DYNAMIC_CHUNKSIZE_NUMBER`: memory will be allocated in
* multiples of this size, defaulting to 1024.
*
* \returns a pointer to a new SDL_IOStream structure, or NULL if it fails;
* \returns a pointer to a new SDL_IOStream structure or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -354,7 +354,7 @@ extern SDL_DECLSPEC SDL_IOStream *SDLCALL SDL_IOFromDynamicMem(void);
* \param iface the function pointers that implement this SDL_IOStream.
* \param userdata the app-controlled pointer that is passed to iface's
* functions when called.
* \returns a pointer to the allocated memory on success, or NULL on failure;
* \returns a pointer to the allocated memory on success or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -488,7 +488,7 @@ extern SDL_DECLSPEC Sint64 SDLCALL SDL_TellIO(SDL_IOStream *context);
* \param context a pointer to an SDL_IOStream structure.
* \param ptr a pointer to a buffer to read data into.
* \param size the number of bytes to read from the data source.
* \returns the number of bytes read, or 0 on end of file or other error.
* \returns the number of bytes read, or 0 on end of file or other failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -515,7 +515,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_ReadIO(SDL_IOStream *context, void *ptr,
* \param ptr a pointer to a buffer containing data to write.
* \param size the number of bytes to write.
* \returns the number of bytes written, which will be less than `size` on
* error; call SDL_GetError() for more information.
* failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -535,7 +535,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_WriteIO(SDL_IOStream *context, const void
* \param fmt a printf() style format string.
* \param ... additional parameters matching % tokens in the `fmt` string, if
* any.
* \returns the number of bytes written, or 0 on error; call SDL_GetError()
* \returns the number of bytes written or 0 on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
@ -553,7 +553,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOprintf(SDL_IOStream *context, SDL_PRINT
* \param context a pointer to an SDL_IOStream structure.
* \param fmt a printf() style format string.
* \param ap a variable argument list.
* \returns the number of bytes written, or 0 on error; call SDL_GetError()
* \returns the number of bytes written or 0 on failure; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
@ -576,7 +576,7 @@ extern SDL_DECLSPEC size_t SDLCALL SDL_IOvprintf(SDL_IOStream *context, SDL_PRIN
* \param datasize if not NULL, will store the number of bytes read.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \returns the data, or NULL if there was an error.
* \returns the data or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -595,7 +595,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadFile_IO(SDL_IOStream *src, size_t *dat
*
* \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.
* \returns the data or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -643,7 +643,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS8(SDL_IOStream *src, Sint8 *value)
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -659,7 +659,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16LE(SDL_IOStream *src, Uint16 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -675,7 +675,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16LE(SDL_IOStream *src, Sint16 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -691,7 +691,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU16BE(SDL_IOStream *src, Uint16 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -707,7 +707,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS16BE(SDL_IOStream *src, Sint16 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -723,7 +723,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32LE(SDL_IOStream *src, Uint32 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -739,7 +739,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32LE(SDL_IOStream *src, Sint32 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -755,7 +755,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU32BE(SDL_IOStream *src, Uint32 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -771,7 +771,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS32BE(SDL_IOStream *src, Sint32 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -787,7 +787,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64LE(SDL_IOStream *src, Uint64 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -803,7 +803,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64LE(SDL_IOStream *src, Sint64 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -819,7 +819,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadU64BE(SDL_IOStream *src, Uint64 *va
*
* \param src the stream from which to read data.
* \param value a pointer filled in with the data read.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -839,7 +839,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_ReadS64BE(SDL_IOStream *src, Sint64 *va
*
* \param dst the SDL_IOStream to write to.
* \param value the byte value to write.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -851,7 +851,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU8(SDL_IOStream *dst, Uint8 value)
*
* \param dst the SDL_IOStream to write to.
* \param value the byte value to write.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -868,7 +868,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS8(SDL_IOStream *dst, Sint8 value)
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -885,7 +885,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16LE(SDL_IOStream *dst, Uint16 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -901,7 +901,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16LE(SDL_IOStream *dst, Sint16 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -917,7 +917,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU16BE(SDL_IOStream *dst, Uint16 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -934,7 +934,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS16BE(SDL_IOStream *dst, Sint16 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -951,7 +951,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32LE(SDL_IOStream *dst, Uint32 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -967,7 +967,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32LE(SDL_IOStream *dst, Sint32 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -983,7 +983,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU32BE(SDL_IOStream *dst, Uint32 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -1000,7 +1000,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS32BE(SDL_IOStream *dst, Sint32 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -1017,7 +1017,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64LE(SDL_IOStream *dst, Uint64 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -1033,7 +1033,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteS64LE(SDL_IOStream *dst, Sint64 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -1049,7 +1049,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_WriteU64BE(SDL_IOStream *dst, Uint64 va
*
* \param dst the stream to which data will be written.
* \param value the data to be written, in native format.
* \returns SDL_TRUE on successful write, SDL_FALSE on failure; call
* \returns SDL_TRUE on successful write or SDL_FALSE on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

8
include/SDL3/SDL_joystick.h
View file

@ -212,8 +212,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasJoystick(void);
*
* \param count a pointer filled in with the number of joysticks returned.
* \returns a 0 terminated array of joystick instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -364,7 +364,7 @@ extern SDL_DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickTypeForID(SDL_Joysti
* for use.
*
* \param instance_id the joystick instance ID.
* \returns a joystick identifier or NULL if an error occurred; call
* \returns a joystick identifier or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -470,7 +470,7 @@ typedef struct SDL_VirtualJoystickDesc
* Attach a new virtual joystick.
*
* \param desc joystick description.
* \returns the joystick instance ID, or 0 if an error occurred; call
* \returns the joystick instance ID, or 0 on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

6
include/SDL3/SDL_keyboard.h
View file

@ -75,8 +75,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasKeyboard(void);
*
* \param count a pointer filled in with the number of keyboards returned.
* \returns a 0 terminated array of keyboards instance IDs which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -93,7 +93,7 @@ extern SDL_DECLSPEC SDL_KeyboardID *SDLCALL SDL_GetKeyboards(int *count);
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param instance_id the keyboard instance ID.
* \returns the name of the selected keyboard, or NULL on failure; call
* \returns the name of the selected keyboard or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

5
include/SDL3/SDL_loadso.h
View file

@ -56,8 +56,7 @@ extern "C" {
* Dynamically load a shared object.
*
* \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.
* \returns an opaque pointer to the object handle or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -83,7 +82,7 @@ extern SDL_DECLSPEC void *SDLCALL SDL_LoadObject(const char *sofile);
*
* \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
* \returns a pointer to the function or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

6
include/SDL3/SDL_mouse.h
View file

@ -137,8 +137,8 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_HasMouse(void);
*
* \param count a pointer filled in with the number of mice returned.
* \returns a 0 terminated array of mouse instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free(), or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*
@ -482,7 +482,7 @@ extern SDL_DECLSPEC SDL_Cursor *SDLCALL SDL_GetCursor(void);
* You do not have to call SDL_DestroyCursor() on the return value, but it is
* safe to do so.
*
* \returns the default cursor on success or NULL on failure.
* \returns the default cursor on success or NULL on failuree; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

2
include/SDL3/SDL_pen.h
View file

@ -156,7 +156,7 @@ typedef enum SDL_PenSubtype
*
* \param count the number of pens in the array (number of array elements
* minus 1, i.e., not counting the terminator 0).
* \returns a 0 terminated array of SDL_PenID values, or NULL on error. The
* \returns a 0 terminated array of SDL_PenID values, or NULL on failure. The
* array must be freed with SDL_free(). On a NULL return,
* SDL_GetError() is set.
*

2
include/SDL3/SDL_properties.h
View file

@ -450,7 +450,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetFloatProperty(SDL_PropertiesID props, c
* \param name the name of the property to query.
* \param default_value the default value of the property.
* \returns the value of the property, or `default_value` if it is not set or
* not a float property.
* not a boolean property.
*
* \threadsafety It is safe to call this function from any thread.
*

21
include/SDL3/SDL_render.h
View file

@ -327,8 +327,7 @@ extern SDL_DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *render
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param renderer the rendering context.
* \returns the name of the selected renderer, or NULL if the renderer is
* invalid.
* \returns the name of the selected renderer, or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1705,7 +1704,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderClear(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.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1736,7 +1736,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const S
* \param y1 the y coordinate of the start point.
* \param x2 the x coordinate of the end point.
* \param y2 the y coordinate of the end point.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1766,7 +1767,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SD
* \param renderer the renderer which should draw a rectangle.
* \param rect a pointer to the destination rectangle, or NULL to outline the
* entire rendering target.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1797,7 +1799,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SD
* \param renderer the renderer which should fill a rectangle.
* \param rect a pointer to the destination rectangle, or NULL for the entire
* rendering target.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1831,7 +1834,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, cons
* texture.
* \param dstrect a pointer to the destination rectangle, or NULL for the
* entire rendering target.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -1881,7 +1885,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer,
* array, if NULL all vertices will be rendered in sequential
* order.
* \param num_indices number of indices.
* \returns 0 on success, or -1 if the operation is not supported.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*

12
include/SDL3/SDL_sensor.h
View file

@ -148,8 +148,8 @@ typedef enum SDL_SensorType
*
* \param count a pointer filled in with the number of sensors returned.
* \returns a 0 terminated array of sensor instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free(), or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -199,7 +199,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableTypeForID(SDL_SensorID i
* Open a sensor for use.
*
* \param instance_id the sensor instance ID.
* \returns an SDL_Sensor sensor object, or NULL if an error occurred.
* \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -209,7 +209,7 @@ extern SDL_DECLSPEC SDL_Sensor *SDLCALL SDL_OpenSensor(SDL_SensorID instance_id)
* Return the SDL_Sensor associated with an instance ID.
*
* \param instance_id the sensor instance ID.
* \returns an SDL_Sensor object.
* \returns an SDL_Sensor object or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -232,7 +232,7 @@ extern SDL_DECLSPEC SDL_PropertiesID SDLCALL SDL_GetSensorProperties(SDL_Sensor
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param sensor the SDL_Sensor object.
* \returns the sensor name, or NULL if `sensor` is NULL.
* \returns the sensor name or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -263,7 +263,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetSensorNonPortableType(SDL_Sensor *sensor)
* Get the instance ID of a sensor.
*
* \param sensor the SDL_Sensor object to inspect.
* \returns the sensor instance ID, or 0 if `sensor` is NULL.
* \returns the sensor instance ID, or 0 on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

6
include/SDL3/SDL_storage.h
View file

@ -227,7 +227,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_StorageReady(SDL_Storage *storage);
* \param storage a storage container to query.
* \param path the relative path of the file to query.
* \param length a pointer to be filled with the file's length.
* \returns 0 if the file could be queried, a negative value otherwise; call
* \returns 0 if the file could be queried or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -245,7 +245,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetStorageFileSize(SDL_Storage *storage, con
* \param path the relative path of the file to read.
* \param destination a client-provided buffer to read the file into.
* \param length the length of the destination buffer.
* \returns 0 if the file was read, a negative value otherwise; call
* \returns 0 if the file was read or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -263,7 +263,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_ReadStorageFile(SDL_Storage *storage, const
* \param path the relative path of the file to write.
* \param source a client-provided buffer to write from.
* \param length the length of the source buffer.
* \returns 0 if the file was written, a negative value otherwise; call
* \returns 0 if the file was written or a negative error code on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

18
include/SDL3/SDL_surface.h
View file

@ -128,7 +128,7 @@ typedef struct SDL_Surface
* \param width the width of the surface.
* \param height the height of the surface.
* \param format the SDL_PixelFormat for the new surface's pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* \returns the new SDL_Surface structure that is created or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -156,7 +156,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_CreateSurface(int width, int height
* \param format the SDL_PixelFormat for the new surface's pixel format.
* \param pixels a pointer to existing pixel data.
* \param pitch the number of bytes between each row, including padding.
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* \returns the new SDL_Surface structure that is created or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -355,8 +355,8 @@ extern SDL_DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
* \param src the data stream for the surface.
* \param closeio if SDL_TRUE, calls SDL_CloseIO() on `src` before returning,
* even in the case of an error.
* \returns a pointer to a new SDL_Surface structure or NULL if there was an
* error; call SDL_GetError() for more information.
* \returns a pointer to a new SDL_Surface structure or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -373,8 +373,8 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_IO(SDL_IOStream *src, SDL_b
* will result in a memory leak.
*
* \param file the BMP file to load.
* \returns a pointer to a new SDL_Surface structure or NULL if there was an
* error; call SDL_GetError() for more information.
* \returns a pointer to a new SDL_Surface structure or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -688,7 +688,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_FlipSurface(SDL_Surface *surface, SDL_FlipMo
* The returned surface should be freed with SDL_DestroySurface().
*
* \param surface the surface to duplicate.
* \returns a copy of the surface, or NULL on failure; call SDL_GetError() for
* \returns a copy of the surface or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
@ -710,7 +710,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_DuplicateSurface(SDL_Surface *surfa
*
* \param surface the existing SDL_Surface structure to convert.
* \param format the new pixel format.
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* \returns the new SDL_Surface structure that is created or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -733,7 +733,7 @@ extern SDL_DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface(SDL_Surface *surface
* \param palette an optional palette to use for indexed formats, may be NULL.
* \param colorspace the new colorspace.
* \param props an SDL_PropertiesID with additional color properties, or 0.
* \returns the new SDL_Surface structure that is created or NULL if it fails;
* \returns the new SDL_Surface structure that is created or NULL on failure;
* call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.

8
include/SDL3/SDL_system.h
View file

@ -162,7 +162,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetX11EventHook(SDL_X11EventHook callback,
*
* \param threadID the Unix thread ID to change priority of.
* \param priority the new, Unix-specific, priority value.
* \returns 0 on success, or -1 on error.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -280,7 +280,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_SetiOSEventPump(SDL_bool enabled);
* rationale being that the SDL headers can avoid including jni.h.
*
* \returns a pointer to Java native interface object (JNIEnv) to which the
* current thread is attached, or 0 on error.
* current thread is attached, or NULL on failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -304,7 +304,7 @@ extern SDL_DECLSPEC void * SDLCALL SDL_GetAndroidJNIEnv(void);
* https://docs.oracle.com/javase/1.5.0/docs/guide/jni/spec/functions.html
*
* \returns the jobject representing the instance of the Activity class of the
* Android application, or NULL on error.
* Android application, or NULL on failure; call SDL_GetError() for more information.
*
* \threadsafety It is safe to call this function from any thread.
*
@ -813,7 +813,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetGDKTaskQueue(XTaskQueueHandle * outTaskQu
*
* \param outUserHandle a pointer to be filled in with the default user
* handle.
* \returns 0 if success, -1 if any error occurs.
* \returns 0 if success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

21
include/SDL3/SDL_time.h
View file

@ -95,8 +95,7 @@ typedef enum SDL_TimeFormat
* format, may be NULL.
* \param timeFormat a pointer to the SDL_TimeFormat to hold the returned time
* format, may be NULL.
* \returns 0 on success or -1 on error; call SDL_GetError() for more
* information.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -107,8 +106,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDateTimeLocalePreferences(SDL_DateFormat
* Jan 1, 1970 in Universal Coordinated Time (UTC).
*
* \param ticks the SDL_Time to hold the returned tick count.
* \returns 0 on success or -1 on error; call SDL_GetError() for more
* information.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -123,8 +121,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetCurrentTime(SDL_Time *ticks);
* \param localTime the resulting SDL_DateTime will be expressed in local time
* if true, otherwise it will be in Universal Coordinated
* Time (UTC).
* \returns 0 on success or -1 on error; call SDL_GetError() for more
* information.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -138,8 +135,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_TimeToDateTime(SDL_Time ticks, SDL_DateTime
*
* \param dt the source SDL_DateTime.
* \param ticks the resulting SDL_Time.
* \returns 0 on success or -1 on error; call SDL_GetError() for more
* information.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -181,8 +177,7 @@ extern SDL_DECLSPEC SDL_Time SDLCALL SDL_TimeFromWindows(Uint32 dwLowDateTime, U
*
* \param year the year.
* \param month the month [1-12].
* \returns the number of days in the requested month, otherwise -1; call
* SDL_GetError() for more information.
* \returns the number of days in the requested month or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -194,8 +189,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDaysInMonth(int year, int month);
* \param year the year component of the date.
* \param month the month component of the date.
* \param day the day component of the date.
* \returns the day of year [0-365] if the date is valid, otherwise -1; call
* SDL_GetError() for more information.
* \returns the day of year [0-365] if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -207,8 +201,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_GetDayOfYear(int year, int month, int day);
* \param year the year component of the date.
* \param month the month component of the date.
* \param day the day component of the date.
* \returns a value between 0 and 6 (0 being Sunday) if the date is valid,
* otherwise -1; call SDL_GetError() for more information.
* \returns a value between 0 and 6 (0 being Sunday) if the date is valid or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/

4
include/SDL3/SDL_timer.h
View file

@ -182,7 +182,7 @@ typedef Uint32 (SDLCALL *SDL_TimerCallback)(void *userdata, SDL_TimerID timerID,
* \param callback the SDL_TimerCallback function to call when the specified
* `interval` elapses.
* \param userdata a pointer that is passed to `callback`.
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* \returns a timer ID or 0 on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.
@ -245,7 +245,7 @@ typedef Uint64 (SDLCALL *SDL_NSTimerCallback)(void *userdata, SDL_TimerID timerI
* \param callback the SDL_TimerCallback function to call when the specified
* `interval` elapses.
* \param userdata a pointer that is passed to `callback`.
* \returns a timer ID or 0 if an error occurs; call SDL_GetError() for more
* \returns a timer ID or 0 on failure; call SDL_GetError() for more
* information.
*
* \threadsafety It is safe to call this function from any thread.

12
include/SDL3/SDL_touch.h
View file

@ -86,8 +86,8 @@ typedef struct SDL_Finger
* \param count a pointer filled in with the number of devices returned, can
* be NULL.
* \returns a 0 terminated array of touch device IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free(), or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -99,8 +99,8 @@ extern SDL_DECLSPEC SDL_TouchID *SDLCALL SDL_GetTouchDevices(int *count);
* The returned string follows the SDL_GetStringRule, and will be automatically freed later.
*
* \param touchID the touch device instance ID.
* \returns touch device name, or NULL on error; call SDL_GetError() for more
* details.
* \returns touch device name, or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -123,8 +123,8 @@ extern SDL_DECLSPEC SDL_TouchDeviceType SDLCALL SDL_GetTouchDeviceType(SDL_Touch
* \param count a pointer filled in with the number of fingers returned, can
* be NULL.
* \returns a NULL terminated array of SDL_Finger pointers which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*/

25
include/SDL3/SDL_video.h
View file

@ -394,8 +394,8 @@ extern SDL_DECLSPEC SDL_SystemTheme SDLCALL SDL_GetSystemTheme(void);
* \param count a pointer filled in with the number of displays returned, may
* be NULL.
* \returns a 0 terminated array of display instance IDs which should be freed
* with SDL_free(), or NULL on error; call SDL_GetError() for more
* details.
* with SDL_free(), or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -533,8 +533,8 @@ extern SDL_DECLSPEC SDL_DisplayOrientation SDLCALL SDL_GetCurrentDisplayOrientat
* big on this display, to aid in readability.
*
* \param displayID the instance ID of the display to query.
* \returns the content scale of the display, or 0.0f on error; call
* SDL_GetError() for more details.
* \returns the content scale of the display, or 0.0f on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -557,8 +557,8 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetDisplayContentScale(SDL_DisplayID displ
* \param displayID the instance ID of the display to query.
* \param count a pointer filled in with the number of display modes returned.
* \returns a NULL terminated array of display mode pointers which should be
* freed with SDL_free(), or NULL on error; call SDL_GetError() for
* more details.
* freed with SDL_free(), or NULL on failure; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -584,7 +584,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode **SDLCALL SDL_GetFullscreenDisplayMode
* \param include_high_density_modes boolean to include high density modes in
* the search.
* \returns a pointer to the closest display mode equal to or larger than the
* desired mode, or NULL on error; call SDL_GetError() for more
* desired mode, or NULL on failure; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.
@ -603,7 +603,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetClosestFullscreenDispl
* display mode.
*
* \param displayID the instance ID of the display to query.
* \returns a pointer to the desktop display mode or NULL on error; call
* \returns a pointer to the desktop display mode or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -622,7 +622,7 @@ extern SDL_DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDesktopDisplayMode(SDL
* display mode.
*
* \param displayID the instance ID of the display to query.
* \returns a pointer to the desktop display mode or NULL on error; call
* \returns a pointer to the desktop display mode or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -2173,8 +2173,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetWindowOpacity(SDL_Window *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.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -2583,8 +2582,8 @@ extern SDL_DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int *value)
* SDL_GLContext is opaque to the application.
*
* \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.
* \returns the OpenGL context associated with `window` or NULL on failure; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*

6
include/SDL3/SDL_vulkan.h
View file

@ -119,7 +119,7 @@ extern SDL_DECLSPEC int SDLCALL SDL_Vulkan_LoadLibrary(const char *path);
* `vkGetInstanceProcAddr =
* (PFN_vkGetInstanceProcAddr)SDL_Vulkan_GetVkGetInstanceProcAddr();`
*
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on error.
* \returns the function pointer for `vkGetInstanceProcAddr` or NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*/
@ -149,7 +149,7 @@ extern SDL_DECLSPEC void SDLCALL SDL_Vulkan_UnloadLibrary(void);
* You should not free the returned array; it is owned by SDL.
*
* \param count a pointer filled in with the number of extensions returned.
* \returns an array of extension name strings on success, NULL on error.
* \returns an array of extension name strings on success, NULL on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -173,7 +173,7 @@ extern SDL_DECLSPEC char const* const* SDLCALL SDL_Vulkan_GetInstanceExtensions(
* allocator that creates the surface. Can be NULL.
* \param surface a pointer to a VkSurfaceKHR handle to output the newly
* created surface.
* \returns 0 on success, -1 on error (check SDL_GetError() for specifics).
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*