From 1bbc897e48ebf8538fcce0b1874381bb236f3c5f Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Mon, 16 Sep 2024 12:55:37 -0700
Subject: [PATCH] Updated documentation for bool return type
Also updated the test CRC functions to return bool.
---
include/SDL3/SDL_audio.h | 2 +-
include/SDL3/SDL_render.h | 2 +-
include/SDL3/SDL_surface.h | 2 +-
include/SDL3/SDL_test_crc32.h | 21 ++++++++-------
include/SDL3/SDL_video.h | 6 ++---
src/test/SDL_test_crc32.c | 48 +++++++++++++++++------------------
6 files changed, 42 insertions(+), 39 deletions(-)
diff --git a/include/SDL3/SDL_audio.h b/include/SDL3/SDL_audio.h
index d7af95bc71992..7c37d5708d1aa 100644
--- a/include/SDL3/SDL_audio.h
+++ b/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.
diff --git a/include/SDL3/SDL_render.h b/include/SDL3/SDL_render.h
index 957c19ef60e04..7ff5a9da5ed45 100644
--- a/include/SDL3/SDL_render.h
+++ b/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.
diff --git a/include/SDL3/SDL_surface.h b/include/SDL3/SDL_surface.h
index aafe574dd6499..a994cbaf3ed63 100644
--- a/include/SDL3/SDL_surface.h
+++ b/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.
diff --git a/include/SDL3/SDL_test_crc32.h b/include/SDL3/SDL_test_crc32.h
index 0c37b7031a5cc..544d7332c203c 100644
--- a/include/SDL3/SDL_test_crc32.h
+++ b/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);
-int 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_Crc32CalcStart(SDLTest_Crc32Context *crcContext, CrcUint32 *crc32);
+SDL_bool SDLCALL SDLTest_Crc32CalcEnd(SDLTest_Crc32Context *crcContext, 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
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index 59ba3ab865b2b..cbb9ad9fa2cbd 100644
--- a/include/SDL3/SDL_video.h
+++ b/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).
diff --git a/src/test/SDL_test_crc32.c b/src/test/SDL_test_crc32.c
index b079daed0e69a..0421fac75d8b0 100644
--- a/src/test/SDL_test_crc32.c
+++ b/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)) {
- return -1;
+ if (!SDLTest_Crc32CalcStart(crcContext, crc32)) {
+ return SDL_FALSE;
}
- if (SDLTest_Crc32CalcBuffer(crcContext, inBuf, inLen, crc32)) {
- return -1;
+ if (!SDLTest_Crc32CalcBuffer(crcContext, inBuf, inLen, crc32)) {
+ return SDL_FALSE;
}
- if (SDLTest_Crc32CalcEnd(crcContext, crc32)) {
- return -1;
+ if (!SDLTest_Crc32CalcEnd(crcContext, crc32)) {
+ 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;
}