Add error returns to void functions that can fail/set errors.

This takes care of the last set of void functions that could
potentially be shifted to instead return an int indicating success and
setting an error in case of an error.

include/SDL3/SDL_audio.h

@@ -801,6 +801,10 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
 /**
  * Clear any pending data in the stream without converting it
  *
+ * \param   stream The audio stream to clear
+ * \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.
  *
  * \sa SDL_CreateAudioStream
@@ -810,7 +814,7 @@ extern DECLSPEC int SDLCALL SDL_FlushAudioStream(SDL_AudioStream *stream);
  * \sa SDL_FlushAudioStream
  * \sa SDL_DestroyAudioStream
  */
-extern DECLSPEC void SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
+extern DECLSPEC int SDLCALL SDL_ClearAudioStream(SDL_AudioStream *stream);
 
 /**
  * Free an audio stream

include/SDL3/SDL_gamepad.h

@@ -537,10 +537,12 @@ 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.
  *
  * \since This function is available since SDL 3.0.0.
  */
-extern DECLSPEC void SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index);
+extern DECLSPEC int SDLCALL SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index);
 
 /**
  * Get the USB vendor ID of an opened gamepad, if available.

include/SDL3/SDL_guid.h

@@ -66,12 +66,14 @@ typedef struct {
  * \param guid the ::SDL_GUID you wish to convert to string
  * \param pszGUID buffer in which to write the ASCII string
  * \param cbGUID the size of pszGUID
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
  * \sa SDL_GUIDFromString
  */
-extern DECLSPEC void SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID);
+extern DECLSPEC int SDLCALL SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID);
 
 /**
  * Convert a GUID string into a ::SDL_GUID structure.

include/SDL3/SDL_joystick.h

@@ -597,6 +597,8 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joyst
  * \param guid the SDL_JoystickGUID you wish to convert to string
  * \param pszGUID buffer in which to write the ASCII string
  * \param cbGUID the size of pszGUID
+ * \returns 0 on success or a negative error code on failure; call
+ *          SDL_GetError() for more information.
  *
  * \since This function is available since SDL 3.0.0.
  *
@@ -604,7 +606,7 @@ extern DECLSPEC SDL_JoystickType SDLCALL SDL_GetJoystickType(SDL_Joystick *joyst
  * \sa SDL_GetJoystickGUID
  * \sa SDL_GetJoystickGUIDFromString
  */
-extern DECLSPEC void SDLCALL SDL_GetJoystickGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
+extern DECLSPEC int SDLCALL SDL_GetJoystickGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID);
 
 /**
  * Convert a GUID string into a SDL_JoystickGUID structure.

include/SDL3/SDL_surface.h

@@ -529,13 +529,15 @@ extern DECLSPEC SDL_bool SDLCALL SDL_SetSurfaceClipRect(SDL_Surface *surface,
  *                clipped
  * \param rect an SDL_Rect structure filled in with the clipping rectangle for
  *             the surface
+ * \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.
  *
  * \sa SDL_BlitSurface
  * \sa SDL_SetSurfaceClipRect
  */
-extern DECLSPEC void SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface,
+extern DECLSPEC int SDLCALL SDL_GetSurfaceClipRect(SDL_Surface *surface,
                                              SDL_Rect *rect);
 
 /*

include/SDL3/SDL_version.h

@@ -115,12 +115,14 @@ typedef struct SDL_version
  * This function may be called safely at any time, even before SDL_Init().
  *
  * \param ver the SDL_version structure that contains the version information
+ * \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.
  *
  * \sa SDL_GetRevision
  */
-extern DECLSPEC void SDLCALL SDL_GetVersion(SDL_version * ver);
+extern DECLSPEC int SDLCALL SDL_GetVersion(SDL_version * ver);
 
 /**
  * Get the code revision of SDL that is linked against your program.

src/SDL.c

@@ -513,13 +513,13 @@ void SDL_Quit(void)
 }
 
 /* Get the library version number */
-void SDL_GetVersion(SDL_version *ver)
+int SDL_GetVersion(SDL_version *ver)
 {
     static SDL_bool check_hint = SDL_TRUE;
     static SDL_bool legacy_version = SDL_FALSE;
 
     if (ver == NULL) {
-        return;
+        return SDL_InvalidParamError("ver");
     }
 
     SDL_VERSION(ver);
@@ -534,6 +534,7 @@ void SDL_GetVersion(SDL_version *ver)
         ver->patch = ver->minor;
         ver->minor = 0;
     }
+    return 0;
 }
 
 /* Get the library source revision */

src/SDL_guid.c

@@ -21,13 +21,16 @@
 #include "SDL_internal.h"
 
 /* convert the guid to a printable string */
-void SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID)
+int SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID)
 {
     static const char k_rgchHexToASCII[] = "0123456789abcdef";
     int i;
 
-    if ((pszGUID == NULL) || (cbGUID <= 0)) {
+    if (pszGUID == NULL) {
-        return;
+        return SDL_InvalidParamError("pszGUID");
+    }
+    if (cbGUID <= 0) {
+        return SDL_InvalidParamError("cbGUID");
     }
 
     for (i = 0; i < sizeof(guid.data) && i < (cbGUID - 1) / 2; i++) {
@@ -39,6 +42,7 @@ void SDL_GUIDToString(SDL_GUID guid, char *pszGUID, int cbGUID)
         *pszGUID++ = k_rgchHexToASCII[c & 0x0F];
     }
     *pszGUID = '\0';
+    return 0;
 }
 
 /*-----------------------------------------------------------------------------

src/audio/SDL_audiocvt.c

@@ -1470,10 +1470,10 @@ int SDL_GetAudioStreamAvailable(SDL_AudioStream *stream)
     return stream ? (int)SDL_GetDataQueueSize(stream->queue) : 0;
 }
 
-void SDL_ClearAudioStream(SDL_AudioStream *stream)
+int SDL_ClearAudioStream(SDL_AudioStream *stream)
 {
     if (stream == NULL) {
-        SDL_InvalidParamError("stream");
+        return SDL_InvalidParamError("stream");
     } else {
         SDL_ClearDataQueue(stream->queue, (size_t)stream->packetlen * 2);
         if (stream->reset_resampler_func) {
@@ -1481,6 +1481,7 @@ void SDL_ClearAudioStream(SDL_AudioStream *stream)
         }
         stream->first_run = SDL_TRUE;
         stream->staging_buffer_filled = 0;
+        return 0;
     }
 }
 

src/dynapi/SDL_dynapi_procs.h

@@ -139,7 +139,7 @@ SDL_DYNAPI_PROC(int,SDL_BlitSurfaceScaled,(SDL_Surface *a, const SDL_Rect *b, SD
 SDL_DYNAPI_PROC(int,SDL_BlitSurfaceUnchecked,(SDL_Surface *a, SDL_Rect *b, SDL_Surface *c, SDL_Rect *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(int,SDL_BlitSurfaceUncheckedScaled,(SDL_Surface *a, SDL_Rect *b, SDL_Surface *c, SDL_Rect *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(int,SDL_CaptureMouse,(SDL_bool a),(a),return)
-SDL_DYNAPI_PROC(void,SDL_ClearAudioStream,(SDL_AudioStream *a),(a),)
+SDL_DYNAPI_PROC(int,SDL_ClearAudioStream,(SDL_AudioStream *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_ClearComposition,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_ClearError,(void),(),)
 SDL_DYNAPI_PROC(void,SDL_ClearHints,(void),(),)
@@ -230,7 +230,7 @@ SDL_DYNAPI_PROC(int,SDL_GL_SwapWindow,(SDL_Window *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GL_UnbindTexture,(SDL_Texture *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_GL_UnloadLibrary,(void),(),)
 SDL_DYNAPI_PROC(SDL_GUID,SDL_GUIDFromString,(const char *a),(a),return)
-SDL_DYNAPI_PROC(void,SDL_GUIDToString,(SDL_GUID a, char *b, int c),(a,b,c),)
+SDL_DYNAPI_PROC(int,SDL_GUIDToString,(SDL_GUID a, char *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_GamepadConnected,(SDL_Gamepad *a),(a),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_GamepadEventsEnabled,(void),(),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_GamepadHasAxis,(SDL_Gamepad *a, SDL_GamepadAxis b),(a,b),return)
@@ -322,7 +322,7 @@ SDL_DYNAPI_PROC(SDL_Joystick*,SDL_GetJoystickFromPlayerIndex,(int a),(a),return)
 SDL_DYNAPI_PROC(SDL_JoystickGUID,SDL_GetJoystickGUID,(SDL_Joystick *a),(a),return)
 SDL_DYNAPI_PROC(SDL_JoystickGUID,SDL_GetJoystickGUIDFromString,(const char *a),(a),return)
 SDL_DYNAPI_PROC(void,SDL_GetJoystickGUIDInfo,(SDL_JoystickGUID a, Uint16 *b, Uint16 *c, Uint16 *d, Uint16 *e),(a,b,c,d,e),)
-SDL_DYNAPI_PROC(void,SDL_GetJoystickGUIDString,(SDL_JoystickGUID a, char *b, int c),(a,b,c),)
+SDL_DYNAPI_PROC(int,SDL_GetJoystickGUIDString,(SDL_JoystickGUID a, char *b, int c),(a,b,c),return)
 SDL_DYNAPI_PROC(Uint8,SDL_GetJoystickHat,(SDL_Joystick *a, int b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_JoystickGUID,SDL_GetJoystickInstanceGUID,(SDL_JoystickID a),(a),return)
 SDL_DYNAPI_PROC(SDL_JoystickID,SDL_GetJoystickInstanceID,(SDL_Joystick *a),(a),return)
@@ -417,7 +417,7 @@ SDL_DYNAPI_PROC(SDL_SensorID*,SDL_GetSensors,(int *a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetShapedWindowMode,(SDL_Window *a, SDL_WindowShapeMode *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetSurfaceAlphaMod,(SDL_Surface *a, Uint8 *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetSurfaceBlendMode,(SDL_Surface *a, SDL_BlendMode *b),(a,b),return)
-SDL_DYNAPI_PROC(void,SDL_GetSurfaceClipRect,(SDL_Surface *a, SDL_Rect *b),(a,b),)
+SDL_DYNAPI_PROC(int,SDL_GetSurfaceClipRect,(SDL_Surface *a, SDL_Rect *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetSurfaceColorKey,(SDL_Surface *a, Uint32 *b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_GetSurfaceColorMod,(SDL_Surface *a, Uint8 *b, Uint8 *c, Uint8 *d),(a,b,c,d),return)
 SDL_DYNAPI_PROC(int,SDL_GetSystemRAM,(void),(),return)
@@ -434,7 +434,7 @@ SDL_DYNAPI_PROC(SDL_TouchID,SDL_GetTouchDevice,(int a),(a),return)
 SDL_DYNAPI_PROC(SDL_TouchDeviceType,SDL_GetTouchDeviceType,(SDL_TouchID a),(a),return)
 SDL_DYNAPI_PROC(SDL_Finger*,SDL_GetTouchFinger,(SDL_TouchID a, int b),(a,b),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetTouchName,(int a),(a),return)
-SDL_DYNAPI_PROC(void,SDL_GetVersion,(SDL_version *a),(a),)
+SDL_DYNAPI_PROC(int,SDL_GetVersion,(SDL_version *a),(a),return)
 SDL_DYNAPI_PROC(const char*,SDL_GetVideoDriver,(int a),(a),return)
 SDL_DYNAPI_PROC(int,SDL_GetWindowBordersSize,(SDL_Window *a, int *b, int *c, int *d, int *e),(a,b,c,d,e),return)
 SDL_DYNAPI_PROC(void*,SDL_GetWindowData,(SDL_Window *a, const char *b),(a,b),return)
@@ -643,7 +643,7 @@ SDL_DYNAPI_PROC(void,SDL_SetEventEnabled,(Uint32 a, SDL_bool b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_SetEventFilter,(SDL_EventFilter a, void *b),(a,b),)
 SDL_DYNAPI_PROC(void,SDL_SetGamepadEventsEnabled,(SDL_bool a),(a),)
 SDL_DYNAPI_PROC(int,SDL_SetGamepadLED,(SDL_Gamepad *a, Uint8 b, Uint8 c, Uint8 d),(a,b,c,d),return)
-SDL_DYNAPI_PROC(void,SDL_SetGamepadPlayerIndex,(SDL_Gamepad *a, int b),(a,b),)
+SDL_DYNAPI_PROC(int,SDL_SetGamepadPlayerIndex,(SDL_Gamepad *a, int b),(a,b),return)
 SDL_DYNAPI_PROC(int,SDL_SetGamepadSensorEnabled,(SDL_Gamepad *a, SDL_SensorType b, SDL_bool c),(a,b,c),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_SetHint,(const char *a, const char *b),(a,b),return)
 SDL_DYNAPI_PROC(SDL_bool,SDL_SetHintWithPriority,(const char *a, const char *b, SDL_HintPriority c),(a,b,c),return)

src/joystick/SDL_gamepad.c

@@ -2679,14 +2679,15 @@ int SDL_GetGamepadPlayerIndex(SDL_Gamepad *gamepad)
 /**
  *  Set the player index of an opened gamepad
  */
-void SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index)
+int SDL_SetGamepadPlayerIndex(SDL_Gamepad *gamepad, int player_index)
 {
     SDL_Joystick *joystick = SDL_GetGamepadJoystick(gamepad);
 
     if (joystick == NULL) {
-        return;
+        /* SDL_SetError() will have been called already by SDL_GetGamepadJoystick() */
+        return -1;
     }
-    SDL_SetJoystickPlayerIndex(joystick, player_index);
+    return SDL_SetJoystickPlayerIndex(joystick, player_index);
 }
 
 Uint16 SDL_GetGamepadVendor(SDL_Gamepad *gamepad)

src/joystick/SDL_joystick.c

@@ -2826,9 +2826,9 @@ SDL_JoystickType SDL_GetJoystickType(SDL_Joystick *joystick)
 }
 
 /* convert the guid to a printable string */
-void SDL_GetJoystickGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID)
+int SDL_GetJoystickGUIDString(SDL_JoystickGUID guid, char *pszGUID, int cbGUID)
 {
-    SDL_GUIDToString(guid, pszGUID, cbGUID);
+    return SDL_GUIDToString(guid, pszGUID, cbGUID);
 }
 
 /* convert the string version of a joystick guid to the struct */

src/video/SDL_surface.c

@@ -615,11 +615,16 @@ SDL_SetSurfaceClipRect(SDL_Surface *surface, const SDL_Rect *rect)
     return SDL_GetRectIntersection(rect, &full_rect, &surface->clip_rect);
 }
 
-void SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect)
+int SDL_GetSurfaceClipRect(SDL_Surface *surface, SDL_Rect *rect)
 {
-    if (surface && rect) {
+    if (!surface) {
-        *rect = surface->clip_rect;
+        return SDL_InvalidParamError("surface");
     }
+    if (!rect) {
+        return SDL_InvalidParamError("rect");
+    }
+    *rect = surface->clip_rect;
+    return 0;
 }
 
 /*