Updated documentation for bool return type

Also updated the test CRC functions to return bool.

include/SDL3/SDL_audio.h

@@ -753,7 +753,7 @@ extern SDL_DECLSPEC float SDLCALL SDL_GetAudioDeviceGain(SDL_AudioDeviceID devid
  * Audio devices default to a gain of 1.0f (no change in output).
  *
  * Physical devices may not have their gain changed, only logical devices, and
- * this function will always return -1 when used on physical devices. While it
+ * this function will always return SDL_FALSE when used on physical devices. While it
  * might seem attractive to adjust several logical devices at once in this
  * way, it would allow an app or library to interfere with another portion of
  * the program's otherwise-isolated devices.

include/SDL3/SDL_render.h

@@ -989,7 +989,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *te
  * 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 SDL_FALSE.
  *
  * \param texture the texture to update.
  * \param blendMode the SDL_BlendMode to use for texture blending.

include/SDL3/SDL_surface.h

@@ -584,7 +584,7 @@ extern SDL_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 SDL_FALSE.
  *
  * \param surface the SDL_Surface structure to query.
  * \param key a pointer filled in with the transparent pixel.

include/SDL3/SDL_test_crc32.h

@@ -73,10 +73,11 @@ extern "C" {
  *
  * \param crcContext        pointer to context variable
  *
- * \returns 0 for OK, -1 on error
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
  */
-int SDLCALL SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext);
+SDL_bool SDLCALL SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext);
 
 /*
  * calculate a crc32 from a data block
@@ -86,26 +87,28 @@ int SDLCALL SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext);
  * \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 SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
  */
-int SDLCALL SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32);
+SDL_bool SDLCALL SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32);
 
 /* Same routine broken down into three steps */
-int SDLCALL SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32);
+SDL_bool SDLCALL SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32);
-int SDLCALL SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32);
+SDL_bool SDLCALL SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32);
-int SDLCALL SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32);
+SDL_bool SDLCALL SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32);
 
 /*
  * clean up CRC context
  *
  * \param crcContext        pointer to context variable
  *
- * \returns 0 for OK, -1 on error
+ * \returns SDL_TRUE on success or SDL_FALSE on failure; call SDL_GetError()
+ *          for more information.
  *
 */
 
-int SDLCALL SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext);
+SDL_bool SDLCALL SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext);
 
 /* Ends C function definitions when using C++ */
 #ifdef __cplusplus

include/SDL3/SDL_video.h

@@ -1564,7 +1564,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window
 /**
  * Get the size of a window's borders (decorations) around the client area.
  *
- * Note: If this function fails (returns -1), the size values will be
+ * Note: If this function fails (returns SDL_FALSE), 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.
  *
@@ -1574,7 +1574,7 @@ extern SDL_DECLSPEC SDL_bool SDLCALL SDL_GetWindowAspectRatio(SDL_Window *window
  * 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.
+ * This function also returns SDL_FALSE if getting the information is not supported.
  *
  * \param window the window to query the size values of the border
  *               (decorations) from.
@@ -2188,7 +2188,7 @@ extern SDL_DECLSPEC const SDL_Rect * SDLCALL SDL_GetWindowMouseRect(SDL_Window *
  * 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 SDL_FALSE 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).

src/test/SDL_test_crc32.c

@@ -27,14 +27,14 @@
 */
 #include <SDL3/SDL_test.h>
 
-int SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext)
+SDL_bool SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext)
 {
     int i, j;
     CrcUint32 c;
 
     /* Sanity check context pointer */
     if (!crcContext) {
-        return -1;
+        return SDL_InvalidParamError("crcContext");
     }
 
     /*
@@ -61,35 +61,35 @@ int SDLTest_Crc32Init(SDLTest_Crc32Context *crcContext)
     }
 #endif
 
-    return 0;
+    return SDL_TRUE;
 }
 
 /* Complete CRC32 calculation on a memory block */
-int SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32)
+SDL_bool SDLTest_Crc32Calc(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32)
 {
-    if (SDLTest_Crc32CalcStart(crcContext, crc32)) {
+    if (!SDLTest_Crc32CalcStart(crcContext, crc32)) {
-        return -1;
+        return SDL_FALSE;
     }
 
-    if (SDLTest_Crc32CalcBuffer(crcContext, inBuf, inLen, crc32)) {
+    if (!SDLTest_Crc32CalcBuffer(crcContext, inBuf, inLen, crc32)) {
-        return -1;
+        return SDL_FALSE;
     }
 
-    if (SDLTest_Crc32CalcEnd(crcContext, crc32)) {
+    if (!SDLTest_Crc32CalcEnd(crcContext, crc32)) {
-        return -1;
+        return SDL_FALSE;
     }
 
-    return 0;
+    return SDL_TRUE;
 }
 
 /* Start crc calculation */
 
-int SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32)
+SDL_bool SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32)
 {
     /* Sanity check pointers */
     if (!crcContext) {
         *crc32 = 0;
-        return -1;
+        return SDL_InvalidParamError("crcContext");
     }
 
     /*
@@ -97,17 +97,17 @@ int SDLTest_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32)
      */
     *crc32 = 0xffffffff;
 
-    return 0;
+    return SDL_TRUE;
 }
 
 /* Finish crc calculation */
 
-int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32)
+SDL_bool SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32)
 {
     /* Sanity check pointers */
     if (!crcContext) {
         *crc32 = 0;
-        return -1;
+        return SDL_InvalidParamError("crcContext");
     }
 
     /*
@@ -115,23 +115,23 @@ int SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32)
      */
     *crc32 = (~(*crc32));
 
-    return 0;
+    return SDL_TRUE;
 }
 
 /* Include memory block in crc */
 
-int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32)
+SDL_bool SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, CrcUint32 inLen, CrcUint32 *crc32)
 {
     CrcUint8 *p;
     register CrcUint32 crc;
 
     if (!crcContext) {
         *crc32 = 0;
-        return -1;
+        return SDL_InvalidParamError("crcContext");
     }
 
     if (!inBuf) {
-        return -1;
+        return SDL_InvalidParamError("inBuf");
     }
 
     /*
@@ -147,14 +147,14 @@ int SDLTest_Crc32CalcBuffer(SDLTest_Crc32Context *crcContext, CrcUint8 *inBuf, C
     }
     *crc32 = crc;
 
-    return 0;
+    return SDL_TRUE;
 }
 
-int SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext)
+SDL_bool SDLTest_Crc32Done(SDLTest_Crc32Context *crcContext)
 {
     if (!crcContext) {
-        return -1;
+        return SDL_InvalidParamError("crcContext");
     }
 
-    return 0;
+    return SDL_TRUE;
 }