gallant/SDL2
1
0
Fork 0
Code Issues Pull requests Packages Projects Releases Wiki Activity

Change return -1 on error, to return a negative on error, which allow to be more consistent across functions.

Browse source 
Only SDL_SetError should return explicitly -1.

Comment: JNIenv is NULL on error

Standardize \returns message
This commit is contained in:
Sylvain 2023-02-09 16:08:03 +01:00
parent 7c4ec1867b
commit 105f12c6ce
No known key found for this signature in database
GPG key ID: 5F87E02E5BC0939E
20 changed files with 123 additions and 129 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
include/SDL3/SDL_audio.h
View file

@ -356,7 +356,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetAudioDeviceName(int index,
* \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 or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -390,7 +390,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 or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -705,7 +705,8 @@ typedef struct SDL_AudioStream SDL_AudioStream;
* \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.
* \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.
*
@ -729,7 +730,7 @@ extern DECLSPEC SDL_AudioStream *SDLCALL SDL_CreateAudioStream(SDL_AudioFormat s
* \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.
* \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.
*
@ -748,7 +749,7 @@ extern DECLSPEC int SDLCALL SDL_PutAudioStreamData(SDL_AudioStream *stream, cons
* \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.
*
* \since This function is available since SDL 3.0.0.
*
@ -1140,8 +1141,8 @@ extern DECLSPEC void SDLCALL SDL_CloseAudioDevice(SDL_AudioDeviceID dev);
* \param dst_data Will be filled with a pointer to converted audio data,
* which should be freed with SDL_free().
* \param dst_len Will be filled with the len of dst_data
* \returns 0 on success or a negative error code on failure. On error,
* *dst_data will be NULL and so not allocated.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
* On error, *dst_data will be NULL and so not allocated.
*
* \since This function is available since SDL 3.0.0.
*

23
include/SDL3/SDL_gamepad.h
View file

@ -174,7 +174,7 @@ typedef struct SDL_GamepadBinding
*
* \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.
* or a negative error code on failure; call SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
*
@ -202,7 +202,7 @@ extern DECLSPEC int SDLCALL SDL_AddGamepadMapping(const char *mappingString);
*
* \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()
* \returns the number of mappings added or a negative error code; call SDL_GetError()
* for more information.
*
* \since This function is available since SDL 3.0.0.
@ -339,7 +339,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetGamepadInstancePath(SDL_JoystickID in
* This can be called before any gamepads are opened.
*
* \param instance_id the joystick instance ID
* \returns the player index of a gamepad, or -1 if it's not available
* \returns the player index of a gamepad, or a negative error code if it's not available
*
* \since This function is available since SDL 3.0.0.
*
@ -525,7 +525,7 @@ extern DECLSPEC SDL_GamepadType SDLCALL SDL_GetGamepadType(SDL_Gamepad *gamepad)
* For XInput gamepads this returns the XInput user index.
*
* \param gamepad the gamepad object to query.
* \returns the player index for gamepad, or -1 if it's not available.
* \returns the player index for gamepad, or a negative error code if it's not available.
*
* \since This function is available since SDL 3.0.0.
*/
@ -537,8 +537,7 @@ extern DECLSPEC int SDLCALL SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad);
* \param gamepad the gamepad object to adjust.
* \param player_index Player index to assign to this gamepad, or -1 to clear
* the player index and turn off player LEDs.
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
* \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.
*/
@ -879,7 +878,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasSensor(SDL_Gamepad *gamepad, SDL_
* \param gamepad The gamepad to update
* \param type The type of sensor to enable/disable
* \param enabled Whether data reporting should be enabled
* \returns 0 or -1 if an error occurred.
* \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.
*/
@ -917,7 +916,7 @@ extern DECLSPEC float SDLCALL SDL_GetGamepadSensorDataRate(SDL_Gamepad *gamepad,
* \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.
* \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.
*/
@ -935,7 +934,7 @@ extern DECLSPEC int SDLCALL SDL_GetGamepadSensorData(SDL_Gamepad *gamepad, SDL_S
* \param high_frequency_rumble The intensity of the high frequency (right)
* rumble motor, from 0 to 0xFFFF
* \param duration_ms The duration of the rumble effect, in milliseconds
* \returns 0, or -1 if rumble isn't supported on this gamepad
* \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.
*
@ -959,7 +958,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleGamepad(SDL_Gamepad *gamepad, Uint16 low_f
* \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 gamepad
* \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.
*
@ -1011,7 +1010,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_GamepadHasRumbleTriggers(SDL_Gamepad *gamep
* \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 gamepad does not have a modifiable LED
* \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.
*/
@ -1023,7 +1022,7 @@ extern DECLSPEC int SDLCALL SDL_SetGamepadLED(SDL_Gamepad *gamepad, Uint8 red, U
* \param gamepad The gamepad to affect
* \param data The data to send to the gamepad
* \param size The size of the data to send to the gamepad
* \returns 0, or -1 if this gamepad or driver doesn't support effect packets
* \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.
*/

24
include/SDL3/SDL_hidapi.h
View file

@ -133,7 +133,7 @@ typedef struct SDL_hid_device_info
*
* Each call to this function should have a matching call to SDL_hid_exit()
*
* \returns 0 on success and -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.
*
@ -147,7 +147,7 @@ extern DECLSPEC int SDLCALL SDL_hid_init(void);
* This function frees all of the static data associated with HIDAPI. It
* should be called at the end of execution to avoid memory leaks.
*
* \returns 0 on success and -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.
*
@ -262,7 +262,7 @@ extern DECLSPEC SDL_hid_device * SDLCALL SDL_hid_open_path(const char *path, int
* \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 negative error code.
*
* \since This function is available since SDL 3.0.0.
*/
@ -281,7 +281,7 @@ extern DECLSPEC int SDLCALL SDL_hid_write(SDL_hid_device *dev, const unsigned ch
* 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 negative error code. If no packet was
* available to be read within the timeout period, this function
* returns 0.
*
@ -301,7 +301,7 @@ extern DECLSPEC int SDLCALL SDL_hid_read_timeout(SDL_hid_device *dev, unsigned c
* \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 negative error code. If no packet was
* available to be read and the handle is in non-blocking mode, this
* function returns 0.
*
@ -321,7 +321,7 @@ extern DECLSPEC int SDLCALL SDL_hid_read(SDL_hid_device *dev, unsigned char *dat
* \param dev A device handle returned from SDL_hid_open().
* \param nonblock enable or not the nonblocking reads - 1 to enable
* nonblocking - 0 to disable nonblocking.
* \returns 0 on success and -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.
*/
@ -345,7 +345,7 @@ extern DECLSPEC int SDLCALL SDL_hid_set_nonblocking(SDL_hid_device *dev, int non
* 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 negative error code.
*
* \since This function is available since SDL 3.0.0.
*/
@ -367,7 +367,7 @@ extern DECLSPEC int SDLCALL SDL_hid_send_feature_report(SDL_hid_device *dev, con
* \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 a negative error code.
*
* \since This function is available since SDL 3.0.0.
*/
@ -390,7 +390,7 @@ extern DECLSPEC int SDLCALL SDL_hid_close(SDL_hid_device *dev);
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \returns 0 on success and -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.
*/
@ -402,7 +402,7 @@ extern DECLSPEC int SDLCALL SDL_hid_get_manufacturer_string(SDL_hid_device *dev,
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \returns 0 on success and -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.
*/
@ -414,7 +414,7 @@ extern DECLSPEC int SDLCALL SDL_hid_get_product_string(SDL_hid_device *dev, wcha
* \param dev A device handle returned from SDL_hid_open().
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \returns 0 on success and -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.
*/
@ -427,7 +427,7 @@ extern DECLSPEC int SDLCALL SDL_hid_get_serial_number_string(SDL_hid_device *dev
* \param string_index The index of the string to get.
* \param string A wide string buffer to put the data into.
* \param maxlen The length of the buffer in multiples of wchar_t.
* \returns 0 on success and -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.
*/

20
include/SDL3/SDL_joystick.h
View file

@ -188,7 +188,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetJoystickInstancePath(SDL_JoystickID i
* This can be called before any joysticks are opened.
*
* \param instance_id the joystick instance ID
* \returns the player index of a joystick, or -1 if it's not available
* \returns the player index of a joystick, or a negative error code if it's not available
*
* \since This function is available since SDL 3.0.0.
*
@ -373,7 +373,7 @@ extern DECLSPEC SDL_JoystickID SDLCALL SDL_AttachVirtualJoystickEx(const SDL_Vir
*
* \param instance_id the joystick instance ID, previously returned from
* SDL_AttachVirtualJoystick()
* \returns 0 on success, or -1 if an error occurred.
* \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.
*/
@ -405,7 +405,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_IsJoystickVirtual(SDL_JoystickID instance_i
* \param joystick the virtual joystick on which to set state.
* \param axis the specific axis on the virtual joystick to set.
* \param value the new value for the specified axis.
* \returns 0 on success, -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.
*/
@ -423,7 +423,7 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualAxis(SDL_Joystick *joystick, i
* \param joystick the virtual joystick on which to set state.
* \param button the specific button on the virtual joystick to set.
* \param value the new value for the specified button.
* \returns 0 on success, -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.
*/
@ -441,7 +441,7 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickVirtualButton(SDL_Joystick *joystick,
* \param joystick the virtual joystick on which to set state.
* \param hat the specific hat on the virtual joystick to set.
* \param value the new value for the specified hat.
* \returns 0 on success, -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.
*/
@ -481,7 +481,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetJoystickPath(SDL_Joystick *joystick);
* will not be able to supply this information.
*
* \param joystick the SDL_Joystick obtained from SDL_OpenJoystick()
* \returns the player index, or -1 if it's not available.
* \returns the player index, or a negative error code if it's not available.
*
* \since This function is available since SDL 3.0.0.
*/
@ -868,7 +868,7 @@ extern DECLSPEC Uint8 SDLCALL SDL_GetJoystickButton(SDL_Joystick *joystick,
* \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
* \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.
*
@ -893,7 +893,7 @@ extern DECLSPEC int SDLCALL SDL_RumbleJoystick(SDL_Joystick *joystick, Uint16 lo
* \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
* \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.
*
@ -948,7 +948,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_JoystickHasRumbleTriggers(SDL_Joystick *joy
* \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
* \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.
*/
@ -960,7 +960,7 @@ extern DECLSPEC int SDLCALL SDL_SetJoystickLED(SDL_Joystick *joystick, Uint8 red
* \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
* \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.
*/

2
include/SDL3/SDL_main.h
View file

@ -219,7 +219,7 @@ extern DECLSPEC int SDLCALL SDL_RunApp(int argc, char* argv[], SDL_main_func mai
* what is specified here.
* \param hInst the HINSTANCE to use in WNDCLASSEX::hInstance. If zero, SDL
* will use `GetModuleHandle(NULL)` instead.
* \returns 0 on success, -1 on error. SDL_GetError() may have details.
* \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.
*/

2
include/SDL3/SDL_misc.h
View file

@ -61,7 +61,7 @@ extern "C" {
*
* \param url A valid URL/URI to open. Use `file:///full/path/to/file` for
* local files, if supported.
* \returns 0 on success, or -1 on error; call SDL_GetError() for more
* \returns 0 on success, or a negative error code; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.

4
include/SDL3/SDL_mouse.h
View file

@ -214,8 +214,6 @@ extern DECLSPEC int SDLCALL SDL_WarpMouseGlobal(float x, float y);
* \returns 0 on success or a negative error code on failure; call
* SDL_GetError() for more information.
*
* If relative mode is not supported, this returns -1.
*
* \since This function is available since SDL 3.0.0.
*
* \sa SDL_GetRelativeMouseMode
@ -259,7 +257,7 @@ extern DECLSPEC int SDLCALL SDL_SetRelativeMouseMode(SDL_bool enabled);
* `SDL_HINT_MOUSE_AUTO_CAPTURE` hint to zero.
*
* \param enabled SDL_TRUE to enable capturing, SDL_FALSE to disable.
* \returns 0 on success or -1 if not supported; call SDL_GetError() for more
* \returns 0 on success or a negative error code if not supported; call SDL_GetError() for more
* information.
*
* \since This function is available since SDL 3.0.0.

6
include/SDL3/SDL_mutex.h
View file

@ -166,7 +166,7 @@ extern DECLSPEC SDL_mutex *SDLCALL SDL_CreateMutex(void);
* other threads in the system (this is known as a "recursive mutex").
*
* \param mutex the mutex to lock
* \return 0, 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.
*/
@ -183,7 +183,7 @@ extern DECLSPEC int SDLCALL SDL_LockMutex(SDL_mutex * mutex) SDL_ACQUIRE(mutex);
* don't want to wait for it, and will return to it to try again later.
*
* \param mutex the mutex to try to lock
* \returns 0, `SDL_MUTEX_TIMEDOUT`, or -1 on error; call SDL_GetError() for
* \returns 0, `SDL_MUTEX_TIMEDOUT`, or a negative error code; call SDL_GetError() for
* more information.
*
* \since This function is available since SDL 3.0.0.
@ -208,7 +208,7 @@ extern DECLSPEC int SDLCALL SDL_TryLockMutex(SDL_mutex * mutex) SDL_TRY_ACQUIRE(
* It is also an error to unlock a mutex that isn't locked at all.
*
* \param mutex the mutex to unlock.
* \returns 0, 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.
*/

65
include/SDL3/SDL_render.h
View file

@ -214,8 +214,7 @@ extern DECLSPEC const char *SDLCALL SDL_GetRenderDriver(int index);
* 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.
* \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.
*
@ -306,8 +305,7 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer);
* \param renderer the rendering context
* \param info an SDL_RendererInfo structure filled with information about the
* current renderer
* \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.
*
@ -324,8 +322,7 @@ extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_Rend
* \param renderer the rendering context
* \param w a pointer filled in with the width in screen coordinates
* \param h a pointer filled in with the height in screen coordinates
* \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.
*
@ -455,8 +452,8 @@ extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture *texture, Uint32 *forma
*
* `srcC = srcC * (color / 255)`
*
* Color modulation is not always supported by the renderer; it will return -1
* if color modulation is not supported.
* Color modulation is not always supported by the renderer; it will return a
* negative error code if color modulation is not supported.
*
* \param texture the texture to update
* \param r the red color value multiplied into copy operations
@ -498,8 +495,8 @@ extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *
*
* `srcA = srcA * (alpha / 255)`
*
* Alpha modulation is not always supported by the renderer; it will return -1
* if alpha modulation is not supported.
* Alpha modulation is not always supported by the renderer; it will return a
* negative error code if alpha modulation is not supported.
*
* \param texture the texture to update
* \param alpha the source alpha value multiplied into copy operations
@ -532,7 +529,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *
* Set the blend mode for a texture, used by SDL_RenderTexture().
*
* If the blend mode is not supported, the closest supported mode is chosen
* and this function returns -1.
* and this function returns a negative error code.
*
* \param texture the texture to update
* \param blendMode the SDL_BlendMode to use for texture blending
@ -567,7 +564,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_Bl
*
* \param texture The texture to update.
* \param scaleMode the SDL_ScaleMode to use for texture scaling.
* \returns 0 on success, or -1 if the texture is not valid.
* \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.
*
@ -580,7 +577,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_Sc
*
* \param texture the texture to query.
* \param scaleMode a pointer filled in with the current scale mode.
* \return 0 on success, or -1 if the texture is not valid.
* \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.
*
@ -593,7 +590,7 @@ extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_Sc
*
* \param texture the texture to update.
* \param userdata the pointer to associate with the texture.
* \returns 0 on success, or -1 if the texture is not valid.
* \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.
*
@ -605,7 +602,7 @@ extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture *texture, void *u
* Get the user-specified pointer associated with a texture
*
* \param texture the texture to query.
* \return the pointer associated with the texture, or NULL if the texture is
* \returns the pointer associated with the texture, or NULL if the texture is
* not valid.
*
* \since This function is available since SDL 3.0.0.
@ -665,8 +662,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Re
* \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
* \returns 0 on success or -1 if the texture is not valid; 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.
*
@ -694,7 +690,7 @@ extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture,
* \param UVplane the raw pixel data for the UV plane.
* \param UVpitch the number of bytes between rows of pixel data for the UV
* plane.
* \return 0 on success, or -1 if the texture is not valid.
* \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.
*/
@ -758,8 +754,9 @@ extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture *texture,
* NULL, the entire texture will be locked
* \param surface this is filled in with an SDL surface representing the
* locked area
* \returns 0 on success, or -1 if the texture is not valid or was not created
* with `SDL_TEXTUREACCESS_STREAMING`
* \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.
*
* \since This function is available since SDL 3.0.0.
*
@ -1161,7 +1158,7 @@ extern 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.
* \return 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.
*/
@ -1173,7 +1170,7 @@ extern DECLSPEC int SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, flo
* \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
* \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.
*/
@ -1187,7 +1184,7 @@ extern DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_F
* \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
* \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.
*/
@ -1200,7 +1197,7 @@ extern DECLSPEC int SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, flo
* \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
* \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.
*/
@ -1212,7 +1209,7 @@ extern DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FP
* \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
* \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.
*/
@ -1225,7 +1222,7 @@ extern DECLSPEC int SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRe
* \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
* \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.
*/
@ -1238,7 +1235,7 @@ extern DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FR
* \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
* \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.
*/
@ -1251,7 +1248,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL
* \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
* \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.
*/
@ -1267,7 +1264,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SD
* texture.
* \param dstrect A pointer to the destination rectangle, or NULL for the
* entire rendering target.
* \return 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.
*/
@ -1290,7 +1287,7 @@ extern DECLSPEC int SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Textur
* 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
* \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.
*/
@ -1312,7 +1309,7 @@ extern DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL
* 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
* \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.
*
@ -1342,7 +1339,7 @@ extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
* 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
* \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.
*
@ -1517,7 +1514,7 @@ extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer *renderer);
* 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
* \returns 0 on success, or -1 if the operation is not supported; call
* \returns 0 on success, or a negative error code if the operation is not supported; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -1533,7 +1530,7 @@ 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
* \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.
*

28
include/SDL3/SDL_rwops.h
View file

@ -52,7 +52,7 @@ extern "C" {
typedef struct SDL_RWops
{
/**
* Return the size of the file in this rwops, or -1 if unknown
* Return the size of the file in this rwops, or a negative error code if unknown
*/
Sint64 (SDLCALL * size) (struct SDL_RWops * context);
@ -60,7 +60,7 @@ typedef struct SDL_RWops
* Seek to \c offset relative to \c whence, one of stdio's whence values:
* SDL_RW_SEEK_SET, SDL_RW_SEEK_CUR, SDL_RW_SEEK_END
*
* \return the final offset in the data stream, or -1 on error.
* \return the final offset in the data stream, or a negative error code.
*/
Sint64 (SDLCALL * seek) (struct SDL_RWops * context, Sint64 offset,
int whence);
@ -73,7 +73,7 @@ typedef struct SDL_RWops
* signed so you definitely cannot overflow the return value on a
* successful run with enormous amounts of data.
*
* \return the number of objects read, or 0 on end of file, or -1 on error.
* \return the number of objects read, or 0 on end of file, or a negative error code.
*/
Sint64 (SDLCALL * read) (struct SDL_RWops * context, void *ptr,
Sint64 size);
@ -81,14 +81,14 @@ typedef struct SDL_RWops
/**
* Write exactly \c size bytes from the area pointed at by \c ptr
* to data stream. May write less than requested (error, non-blocking i/o,
* etc). Returns -1 on error when nothing was written.
* etc). Returns negative error code when nothing was written.
*
* It is an error to use a negative \c size, but this parameter is
* signed so you definitely cannot overflow the return value on a
* successful run with enormous amounts of data.
*
* \return the number of bytes written, which might be less than \c size,
* and -1 on error.
* and negative error code.
*/
Sint64 (SDLCALL * write) (struct SDL_RWops * context, const void *ptr,
Sint64 size);
@ -96,7 +96,7 @@ typedef struct SDL_RWops
/**
* Close and free an allocated SDL_RWops structure.
*
* \return 0 if successful or -1 on write error when flushing data.
* \returns 0 if successful or negative code on write error when flushing data.
*/
int (SDLCALL * close) (struct SDL_RWops * context);
@ -343,7 +343,7 @@ extern DECLSPEC void SDLCALL SDL_DestroyRW(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
* \returns the size of the data stream in the SDL_RWops on success, -1 if
* \returns the size of the data stream in the SDL_RWops on success, negative error code if
* unknown or a negative error code on failure; call SDL_GetError()
* for more information.
*
@ -362,7 +362,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
* - `SDL_RW_SEEK_CUR`: seek relative to current read point
* - `SDL_RW_SEEK_END`: seek relative to the end of data
*
* If this stream can not seek, it will return -1.
* If this stream can not seek, it will return a negative error code.
*
* SDL_RWseek() is actually a wrapper function that calls the SDL_RWops's
* `seek` method appropriately, to simplify application development.
@ -374,7 +374,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWsize(SDL_RWops *context);
* negative
* \param whence any of `SDL_RW_SEEK_SET`, `SDL_RW_SEEK_CUR`,
* `SDL_RW_SEEK_END`
* \returns the final offset in the data stream after the seek or -1 on error.
* \returns the final offset in the data stream after the seek or a negative error code.
*
* \since This function is available since SDL 3.0.0.
*
@ -400,7 +400,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWseek(SDL_RWops *context,
*
* \param context a SDL_RWops data stream object from which to get the current
* offset
* \returns the current offset in the stream, or -1 if the information can not
* \returns the current offset in the stream, or a negative error code if the information can not
* be determined.
*
* \since This function is available since SDL 3.0.0.
@ -420,7 +420,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
*
* This function reads up `size` bytes from the data source to the area
* pointed at by `ptr`. This function may read less bytes than requested. It
* will return zero when the data stream is completely read, or -1 on error.
* will return zero when the data stream is completely read, or a negative error code.
* For streams that support non-blocking operation, if nothing was read
* because it would require blocking, this function returns -2 to distinguish
* that this is not an error or end-of-file, and the caller can try again
@ -436,7 +436,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWtell(SDL_RWops *context);
* \param context a pointer to an SDL_RWops 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, 0 at end of file, -1 on error, and -2
* \returns the number of bytes read, 0 at end of file, negative error code, and -2
* for data not ready with a non-blocking context.
*
* \since This function is available since SDL 3.0.0.
@ -460,7 +460,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWread(SDL_RWops *context, void *ptr, Sint64
* On error, this function still attempts to write as much as possible, so it
* might return a positive value less than the requested write size. If the
* function failed to write anything and there was an actual error, it will
* return -1. For streams that support non-blocking operation, if nothing was
* return a negative error code. For streams that support non-blocking operation, if nothing was
* written because it would require blocking, this function returns -2 to
* distinguish that this is not an error and the caller can try again later.
*
@ -494,7 +494,7 @@ extern DECLSPEC Sint64 SDLCALL SDL_RWwrite(SDL_RWops *context,
*
* SDL_RWclose() closes and cleans up the SDL_RWops stream. It releases any
* resources used by the stream and frees the SDL_RWops itself with
* SDL_DestroyRW(). This returns 0 on success, or -1 if the stream failed to
* SDL_DestroyRW(). This returns 0 on success, or a negative error code if the stream failed to
* flush to its output (e.g. to disk).
*
* Note that if this fails to flush the stream to disk, this function reports

6
include/SDL3/SDL_sensor.h
View file

@ -165,7 +165,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorInstanceType(SDL_SensorID in
* Get the platform dependent type of a sensor.
*
* \param instance_id the sensor instance ID
* \returns the sensor platform dependent type, or -1 if `instance_id` is not
* \returns the sensor platform dependent type, or a negative error code if `instance_id` is not
* valid
*
* \since This function is available since SDL 3.0.0.
@ -217,7 +217,7 @@ extern DECLSPEC SDL_SensorType SDLCALL SDL_GetSensorType(SDL_Sensor *sensor);
* Get the platform dependent type of a sensor.
*
* \param sensor The SDL_Sensor object to inspect
* \returns the sensor platform dependent type, or -1 if `sensor` is NULL.
* \returns the sensor platform dependent type, or a negative error code if `sensor` is NULL.
*
* \since This function is available since SDL 3.0.0.
*/
@ -241,7 +241,7 @@ extern DECLSPEC SDL_SensorID SDLCALL SDL_GetSensorInstanceID(SDL_Sensor *sensor)
* \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.
* \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.
*/

4
include/SDL3/SDL_shape.h
View file

@ -116,7 +116,7 @@ typedef struct SDL_WindowShapeMode {
* \param window The shaped window whose parameters should be set.
* \param shape A surface encoding the desired shape for the window.
* \param shape_mode The parameters to set for the shaped window.
* \return 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
* \returns 0 on success, SDL_INVALID_SHAPE_ARGUMENT on an invalid shape
* argument, or SDL_NONSHAPEABLE_WINDOW if the SDL_Window given does
* not reference a valid shaped window.
*
@ -133,7 +133,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowShape(SDL_Window *window,SDL_Surface *s
* \param window The shaped window whose parameters should be retrieved.
* \param shape_mode An empty shape-mode structure to fill, or NULL to check
* whether the window has a shape.
* \return 0 if the window has a shape and, provided shape_mode was not NULL,
* \returns 0 if the window has a shape and, provided shape_mode was not NULL,
* shape_mode has been filled with the mode data,
* SDL_NONSHAPEABLE_WINDOW if the SDL_Window given is not a shaped
* window, or SDL_WINDOW_LACKS_SHAPE if the SDL_Window given is a

3
include/SDL3/SDL_surface.h
View file

@ -366,7 +366,8 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SurfaceHasColorKey(SDL_Surface *surface);
* The color key is a pixel of the format used by the surface, as generated by
* SDL_MapRGB().
*
* If the surface doesn't have color key enabled this function returns -1.
* If the surface doesn't have color key enabled this function returns negative
* error code.
*
* \param surface the SDL_Surface structure to query
* \param key a pointer filled in with the transparent pixel

12
include/SDL3/SDL_system.h
View file

@ -158,7 +158,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_DXGIGetOutputInfo(SDL_DisplayID displayID,
*
* \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.
*/
@ -173,7 +173,7 @@ extern DECLSPEC int SDLCALL SDL_LinuxSetThreadPriority(Sint64 threadID, int prio
* \param sdlPriority The new SDL_ThreadPriority value.
* \param schedPolicy The new scheduling policy (SCHED_FIFO, SCHED_RR,
* SCHED_OTHER, etc...)
* \returns 0 on success, or -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.
*/
@ -255,7 +255,7 @@ extern DECLSPEC void SDLCALL SDL_iPhoneSetEventPump(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 error.
*
* \since This function is available since SDL 3.0.0.
*
@ -433,7 +433,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permis
*
* Shows toast in UI thread.
*
* For the `gravity` parameter, choose a value from here, or -1 if you don't
* For the `gravity` parameter, choose a value from here, or a negative error code if you don't
* have a preference:
*
* https://developer.android.com/reference/android/view/Gravity
@ -443,7 +443,7 @@ extern DECLSPEC SDL_bool SDLCALL SDL_AndroidRequestPermission(const char *permis
* \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
* \returns 0 if success, -1 if any error occurs.
* \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.
*/
@ -601,7 +601,7 @@ typedef struct XTaskQueueObject * XTaskQueueHandle;
* leak.
*
* \param outTaskQueue a pointer to be filled in with task queue handle.
* \returns 0 if success, -1 if any error occurs.
* \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.
*/

2
include/SDL3/SDL_test_common.h
View file

@ -151,7 +151,7 @@ SDLTest_CommonState *SDLTest_CommonCreateState(char **argv, Uint32 flags);
* \param state The common state describing the test window to create.
* \param index The index of the argument to process in argv[].
*
* \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or -1 on error.
* \returns the number of arguments processed (i.e. 1 for --fullscreen, 2 for --video [videodriver], or a negative error code.
*/
int SDLTest_CommonArg(SDLTest_CommonState *state, int index);

2
include/SDL3/SDL_test_compare.h
View file

@ -51,7 +51,7 @@ extern "C" {
* \param referenceSurface Test Surface used in comparison
* \param allowable_error Allowable difference (=sum of squared difference for each RGB component) in blending accuracy.
*
* \returns 0 if comparison succeeded, >0 (=number of pixels for which the comparison failed) if comparison failed, -1 if any of the surfaces were NULL, -2 if the surface sizes differ.
* \returns 0 if comparison succeeded, >0 (=number of pixels for which the comparison failed) if comparison failed, negative error code if any of the surfaces were NULL, -2 if the surface sizes differ.
*/
int SDLTest_CompareSurfaces(SDL_Surface *surface, SDL_Surface *referenceSurface, int allowable_error);

6
include/SDL3/SDL_test_crc32.h
View file

@ -76,7 +76,7 @@ extern "C" {
*
* \param crcContext pointer to context variable
*
* \returns 0 for OK, -1 on error
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
*/
int SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext);
@ -90,7 +90,7 @@ extern "C" {
* \param inLen length of input buffer
* \param crc32 pointer to Uint32 to store the final CRC into
*
* \returns 0 for OK, -1 on error
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
*/
int SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32);
@ -106,7 +106,7 @@ int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, C
*
* \param crcContext pointer to context variable
*
* \returns 0 for OK, -1 on error
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*
*/

4
include/SDL3/SDL_test_font.h
View file

@ -49,7 +49,7 @@ extern "C" {
* \param y The Y coordinate of the upper left corner of the character.
* \param c The character to draw.
*
* \returns 0 on success, -1 on failure.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*/
int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c);
@ -63,7 +63,7 @@ int SDLTest_DrawCharacter(SDL_Renderer *renderer, float x, float y, Uint32 c);
* \param y The Y coordinate of the upper left corner of the string.
* \param s The string to draw.
*
* \returns 0 on success, -1 on failure.
* \returns 0 on success or a negative error code on failure; call SDL_GetError() for more information.
*/
int SDLTest_DrawString(SDL_Renderer *renderer, float x, float y, const char *s);

22
include/SDL3/SDL_video.h
View file

@ -869,7 +869,7 @@ extern DECLSPEC int SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h
* Get the size of a window's borders (decorations) around the client area, in
* screen coordinates.
*
* Note: If this function fails (returns -1), the size values will be
* Note: If this function fails, the size values will be
* initialized to 0, 0, 0, 0 (if a non-NULL pointer is provided), as if the
* window in question was borderless.
*
@ -879,8 +879,6 @@ extern DECLSPEC int SDLCALL SDL_GetWindowSize(SDL_Window *window, int *w, int *h
* window has been presented and composited, so that the window system has a
* chance to decorate the window and provide the border dimensions to SDL.
*
* 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
* \param top pointer to variable for storing the size of the top border; NULL
@ -1370,7 +1368,7 @@ extern DECLSPEC const SDL_Rect *SDLCALL SDL_GetWindowMouseRect(SDL_Window *windo
* The parameter `opacity` will be clamped internally between 0.0f
* (transparent) and 1.0f (opaque).
*
* This function also returns -1 if setting the opacity isn't supported.
* This function also returns negative error code 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)
@ -1391,7 +1389,7 @@ extern DECLSPEC int SDLCALL SDL_SetWindowOpacity(SDL_Window *window, float opaci
*
* The parameter `opacity` is ignored if it is NULL.
*
* This function also returns -1 if an invalid window was provided.
* This function also returns negative error code 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)
@ -1487,7 +1485,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
* Specifying NULL for a callback disables hit-testing. Hit-testing is
* disabled by default.
*
* Platforms that don't support this functionality will return -1
* Platforms that don't support this functionality will return negative code
* unconditionally, even if you're attempting to disable hit-testing.
*
* Your callback may fire at any time, and its firing does not indicate any
@ -1501,7 +1499,7 @@ typedef SDL_HitTestResult (SDLCALL *SDL_HitTest)(SDL_Window *win,
* \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
* \returns 0 on success or a negative error code (including unsupported); call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.
@ -1883,7 +1881,7 @@ extern DECLSPEC void SDLCALL SDL_EGL_SetEGLAttributeCallbacks(SDL_EGLAttribArray
* the vertical retrace for a given frame, it swaps buffers immediately, which
* might be less jarring for the user during occasional framerate drops. If an
* application requests adaptive vsync and the system does not support it,
* this function will fail and return -1. In such a case, you should probably
* this function will fail and return a negative error code. In such a case, you should probably
* retry the call with 1 for the interval.
*
* Adaptive vsync is implemented for some glX drivers with
@ -1895,8 +1893,8 @@ extern DECLSPEC void SDLCALL SDL_EGL_SetEGLAttributeCallbacks(SDL_EGLAttribArray
*
* \param interval 0 for immediate updates, 1 for updates synchronized with
* 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.
* \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.
*
@ -1912,9 +1910,9 @@ extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval);
*
* \param interval Output interval value. 0 if there is no vertical retrace
* synchronization, 1 if the buffer swap is synchronized with
* the vertical retrace, and -1 if late swaps happen
* the vertical retrace, and negative error code if late swaps happen
* immediately instead of waiting for the next retrace
* \returns 0 on success or -1 error. call SDL_GetError() for more
* \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.

2
include/SDL3/SDL_vulkan.h
View file

@ -95,7 +95,7 @@ typedef VkSurfaceKHR SDL_vulkanSurface; /* for compatibility with Tizen */
* library version.
*
* \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
* \returns 0 on success or a negative error code if the library couldn't be loaded; call
* SDL_GetError() for more information.
*
* \since This function is available since SDL 3.0.0.