SDL_image: Added missing documentation for the quality parameter on AVIF save functions

From a1ee1765a678744c56d8b84f1465dca202bcdf2a Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Thu, 25 Jan 2024 20:35:43 -0800
Subject: [PATCH] Added missing documentation for the quality parameter on AVIF
 save functions

Also cleaned up the wording for freesrc and freedst parameters
---
 include/SDL3_image/SDL_image.h | 41 ++++++++++++++++++++++++----------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/include/SDL3_image/SDL_image.h b/include/SDL3_image/SDL_image.h
index a041d636..585d60ed 100644
--- a/include/SDL3_image/SDL_image.h
+++ b/include/SDL3_image/SDL_image.h
@@ -211,7 +211,7 @@ extern DECLSPEC void SDLCALL IMG_Quit(void);
  * by calling: SDL_SetSurfaceColorKey(image, SDL_RLEACCEL,
  * image->format->colorkey);
  *
- * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * If `freesrc` is SDL_TRUE, the RWops will be closed before returning,
  * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
@@ -238,7 +238,7 @@ extern DECLSPEC void SDLCALL IMG_Quit(void);
  * call to SDL_DestroySurface().
  *
  * \param src an SDL_RWops that data will be read from.
- * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ * \param freesrc SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
  *                to leave it open.
  * \param type a filename extension that represent this data ("BMP", "GIF",
  *             "PNG", etc).
@@ -316,7 +316,7 @@ extern DECLSPEC SDL_Surface * SDLCALL IMG_Load(const char *file);
  * by calling: SDL_SetSurfaceColorKey(image, SDL_RLEACCEL,
  * image->format->colorkey);
  *
- * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * If `freesrc` is SDL_TRUE, the RWops will be closed before returning,
  * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
@@ -337,7 +337,7 @@ extern DECLSPEC SDL_Surface * SDLCALL IMG_Load(const char *file);
  * call to SDL_DestroySurface().
  *
  * \param src an SDL_RWops that data will be read from.
- * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ * \param freesrc SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
  *                to leave it open.
  * \returns a new SDL surface, or NULL on error.
  *
@@ -400,7 +400,7 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture(SDL_Renderer *renderer, co
  * data (but in many cases, this will just end up being 32-bit RGB or 32-bit
  * RGBA).
  *
- * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * If `freesrc` is SDL_TRUE, the RWops will be closed before returning,
  * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
@@ -421,7 +421,7 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture(SDL_Renderer *renderer, co
  *
  * \param renderer the SDL_Renderer to use to create the GPU texture.
  * \param src an SDL_RWops that data will be read from.
- * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ * \param freesrc SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
  *                to leave it open.
  * \returns a new texture, or NULL on error.
  *
@@ -447,7 +447,7 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture_RW(SDL_Renderer *renderer,
  * data (but in many cases, this will just end up being 32-bit RGB or 32-bit
  * RGBA).
  *
- * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * If `freesrc` is SDL_TRUE, the RWops will be closed before returning,
  * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
@@ -474,7 +474,7 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture_RW(SDL_Renderer *renderer,
  *
  * \param renderer the SDL_Renderer to use to create the GPU texture.
  * \param src an SDL_RWops that data will be read from.
- * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ * \param freesrc SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
  *                to leave it open.
  * \param type a filename extension that represent this data ("BMP", "GIF",
  *             "PNG", etc).
@@ -1976,6 +1976,7 @@ extern DECLSPEC SDL_Surface * SDLCALL IMG_ReadXPMFromArrayToRGB888(char **xpm);
  *
  * \param surface the SDL surface to save
  * \param file path on the filesystem to write new file to.
+ * \param quality the desired quality, ranging between 0 (lowest) and 100 (highest)
  * \returns 0 if successful, -1 on error
  *
  * \since This function is available since SDL_image 3.0.0.
@@ -1989,8 +1990,14 @@ extern DECLSPEC int SDLCALL IMG_SaveAVIF(SDL_Surface *surface, const char *file,
  *
  * If you just want to save to a filename, you can use IMG_SaveAVIF() instead.
  *
+ * If `freedst` is SDL_TRUE, the RWops will be closed before returning,
+ * whether this function succeeds or not.
+ *
  * \param surface the SDL surface to save
  * \param dst the SDL_RWops to save the image data to.
+ * \param freedst SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
+ *                to leave it open.
+ * \param quality the desired quality, ranging between 0 (lowest) and 100 (highest)
  * \returns 0 if successful, -1 on error.
  *
  * \since This function is available since SDL_image 3.0.0.
@@ -2019,8 +2026,13 @@ extern DECLSPEC int SDLCALL IMG_SavePNG(SDL_Surface *surface, const char *file);
  *
  * If you just want to save to a filename, you can use IMG_SavePNG() instead.
  *
+ * If `freedst` is SDL_TRUE, the RWops will be closed before returning,
+ * whether this function succeeds or not.
+ *
  * \param surface the SDL surface to save
  * \param dst the SDL_RWops to save the image data to.
+ * \param freedst SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
+ *                to leave it open.
  * \returns 0 if successful, -1 on error.
  *
  * \since This function is available since SDL_image 3.0.0.
@@ -2051,8 +2063,13 @@ extern DECLSPEC int SDLCALL IMG_SaveJPG(SDL_Surface *surface, const char *file,
  *
  * If you just want to save to a filename, you can use IMG_SaveJPG() instead.
  *
+ * \param freedst SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
+ *                to leave it open.
+ *
  * \param surface the SDL surface to save
  * \param dst the SDL_RWops to save the image data to.
+ * \param freedst SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
+ *                to leave it open.
  * \returns 0 if successful, -1 on error.
  *
  * \since This function is available since SDL_image 3.0.0.
@@ -2091,7 +2108,7 @@ extern DECLSPEC IMG_Animation * SDLCALL IMG_LoadAnimation(const char *file);
 /**
  * Load an animation from an SDL_RWops.
  *
- * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * If `freesrc` is SDL_TRUE, the RWops will be closed before returning,
  * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
@@ -2099,7 +2116,7 @@ extern DECLSPEC IMG_Animation * SDLCALL IMG_LoadAnimation(const char *file);
  * call to IMG_FreeAnimation().
  *
  * \param src an SDL_RWops that data will be read from.
- * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ * \param freesrc SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
  *                to leave it open.
  * \returns a new IMG_Animation, or NULL on error.
  *
@@ -2118,7 +2135,7 @@ extern DECLSPEC IMG_Animation * SDLCALL IMG_LoadAnimation_RW(SDL_RWops *src, SDL
  * that it cannot autodetect. If `type` is NULL, SDL_image will rely solely on
  * its ability to guess the format.
  *
- * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * If `freesrc` is SDL_TRUE, the RWops will be closed before returning,
  * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
@@ -2126,7 +2143,7 @@ extern DECLSPEC IMG_Animation * SDLCALL IMG_LoadAnimation_RW(SDL_RWops *src, SDL
  * call to IMG_FreeAnimation().
  *
  * \param src an SDL_RWops that data will be read from.
- * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ * \param freesrc SDL_TRUE to close/free the SDL_RWops before returning, SDL_FALSE
  *                to leave it open.
  * \param type a filename extension that represent this data ("GIF", etc).
  * \returns a new IMG_Animation, or NULL on error.