From 1bbc897e48ebf8538fcce0b1874381bb236f3c5f Mon Sep 17 00:00:00 2001 From: Sam Lantinga 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 d7af95bc71..7c37d5708d 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 957c19ef60..7ff5a9da5e 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 aafe574dd6..a994cbaf3e 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 0c37b7031a..544d7332c2 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 59ba3ab865..cbb9ad9fa2 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 b079daed0e..0421fac75d 100644 --- a/src/test/SDL_test_crc32.c +++ b/src/test/SDL_test_crc32.c @@ -27,14 +27,14 @@ */ #include -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; }