SDL_image: SDL_image.h: Bunch More Work on the documentation.

From 776922c8bafacae65f7922224b4f443425fc806b Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 5 Jul 2022 23:01:08 -0400
Subject: [PATCH] SDL_image.h: Bunch More Work on the documentation.

---
 SDL_image.h | 927 +++++++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 890 insertions(+), 37 deletions(-)

diff --git a/SDL_image.h b/SDL_image.h
index 555dc615..52052d7d 100644
--- a/SDL_image.h
+++ b/SDL_image.h
@@ -197,26 +197,41 @@ extern DECLSPEC void SDLCALL IMG_Quit(void);
  * this if you plan to hand the data to something else or manipulate it
  * further in code.
  *
- * If you are using SDL's 2D rendering API, there is an equivalent call to
- * load images directly into an SDL_Texture for use by the GPU without using a
- * software surface: call IMG_LoadTextureTyped_RW() instead.
+ * There are no guarantees about what format the new SDL_Surface data will be;
+ * in many cases, SDL_image will attempt to supply a surface that exactly
+ * matches the provided image, but in others it might have to convert
+ * (either because the image is in a format that SDL doesn't directly support
+ * or because it's compressed data that could reasonably uncompress to
+ * various formats and SDL_image had to pick one). You can inspect an
+ * SDL_Surface for its specifics, and use SDL_ConvertSurface to then
+ * migrate to any supported format.
  *
  * If the image format supports a transparent pixel, SDL will set the colorkey
  * for the surface. You can enable RLE acceleration on the surface afterwards
  * by calling: SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);
  *
  * If `freesrc` is non-zero, the RWops will be closed before returning,
- * whether this function succeeds or not. SDL_mixer reads everything it needs
+ * whether this function succeeds or not. SDL_image reads everything it needs
  * from the RWops during this call in any case.
  *
+ * Even though this function accepts a file type, SDL_image may still try
+ * other decoders that are capable of detecting file type from the contents
+ * of the image data, but may rely on the caller-provided type string for
+ * formats that it cannot autodetect. If `type` is NULL, SDL_image will
+ * rely solely on its ability to guess the format.
+ *
  * There is a separate function to read files from disk without having to deal
  * with SDL_RWops: `IMG_Load("filename.jpg")` will call this function and
  * manage those details for you, determining the file type from the filename's
  * extension.
  *
  * There is also IMG_Load_RW(), which is equivalent to this function except
- * that it will rely on SDL_image to determine what type of data it is
- * loading.
+ * that it will rely on SDL_image to determine what type of data it is loading,
+ * much like passing a NULL for type.
+ *
+ * If you are using SDL's 2D rendering API, there is an equivalent call
+ * to load images directly into an SDL_Texture for use by the GPU without
+ * using a software surface: call IMG_LoadTextureTyped_RW() instead.
  *
  * When done with the returned surface, the app should dispose of it with a
  * call to SDL_FreeSurface().
@@ -228,8 +243,7 @@ extern DECLSPEC void SDLCALL IMG_Quit(void);
  *             "PNG", etc).
  * \returns a new SDL surface, or NULL on error.
  *
- * \since This function is available since SDL_mixer 2.6.0 (and as a macro
- *        since 2.0.0).
+ * \since This function is available since SDL_image 2.0.0.
  *
  * \sa IMG_Load
  * \sa IMG_Load_RW
@@ -238,10 +252,40 @@ extern DECLSPEC void SDLCALL IMG_Quit(void);
 extern DECLSPEC SDL_Surface * SDLCALL IMG_LoadTyped_RW(SDL_RWops *src, int freesrc, const char *type);
 
 /**
- * Load an image from file
+ * Load an image from a filesystem path into a software surface.
  *
- * \param file file name
- * \returns SDL surface, or NULL on error.
+ * An SDL_Surface is a buffer of pixels in memory accessible by the CPU.
+ * Use this if you plan to hand the data to something else or manipulate it
+ * further in code.
+ *
+ * There are no guarantees about what format the new SDL_Surface data will be;
+ * in many cases, SDL_image will attempt to supply a surface that exactly
+ * matches the provided image, but in others it might have to convert
+ * (either because the image is in a format that SDL doesn't directly support
+ * or because it's compressed data that could reasonably uncompress to
+ * various formats and SDL_image had to pick one). You can inspect an
+ * SDL_Surface for its specifics, and use SDL_ConvertSurface to then
+ * migrate to any supported format.
+ *
+ * If the image format supports a transparent pixel, SDL will set the colorkey
+ * for the surface. You can enable RLE acceleration on the surface afterwards
+ * by calling: SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);
+ *
+ * There is a separate function to read files from an SDL_RWops, if you need
+ * an i/o abstraction to provide data from anywhere instead of a simple
+ * filesystem read; that function is IMG_Load_RW().
+ *
+ * If you are using SDL's 2D rendering API, there is an equivalent call
+ * to load images directly into an SDL_Texture for use by the GPU without
+ * using a software surface: call IMG_LoadTexture() instead.
+ *
+ * When done with the returned surface, the app should dispose of it with
+ * a call to SDL_FreeSurface().
+ *
+ * \param file a path on the filesystem to load an image from.
+ * \returns a new SDL surface, or NULL on error.
+ *
+ * \since This function is available since SDL_image 2.0.0.
  *
  * \sa IMG_LoadTyped_RW
  * \sa IMG_Load_RW
@@ -250,12 +294,51 @@ extern DECLSPEC SDL_Surface * SDLCALL IMG_LoadTyped_RW(SDL_RWops *src, int frees
 extern DECLSPEC SDL_Surface * SDLCALL IMG_Load(const char *file);
 
 /**
- * Load an image from a SDL datasource
+ * Load an image from an SDL data source into a software surface.
  *
- * \param src RWops
- * \param freesrc can be set so that the RWops is freed after this function is
- *                called
- * \returns SDL surface, or NULL on error
+ * An SDL_Surface is a buffer of pixels in memory accessible by the CPU.
+ * Use this if you plan to hand the data to something else or manipulate it
+ * further in code.
+ *
+ * There are no guarantees about what format the new SDL_Surface data will be;
+ * in many cases, SDL_image will attempt to supply a surface that exactly
+ * matches the provided image, but in others it might have to convert
+ * (either because the image is in a format that SDL doesn't directly support
+ * or because it's compressed data that could reasonably uncompress to
+ * various formats and SDL_image had to pick one). You can inspect an
+ * SDL_Surface for its specifics, and use SDL_ConvertSurface to then
+ * migrate to any supported format.
+ *
+ * If the image format supports a transparent pixel, SDL will set the colorkey
+ * for the surface. You can enable RLE acceleration on the surface afterwards
+ * by calling: SDL_SetColorKey(image, SDL_RLEACCEL, image->format->colorkey);
+ *
+ * If `freesrc` is non-zero, 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.
+ *
+ * There is a separate function to read files from disk without having to deal
+ * with SDL_RWops: `IMG_Load("filename.jpg")` will call this function and
+ * manage those details for you, determining the file type from the filename's
+ * extension.
+ *
+ * There is also IMG_LoadTyped_RW(), which is equivalent to this function except
+ * a file extension (like "BMP", "JPG", etc) can be specified, in case SDL_image
+ * cannot autodetect the file format.
+ *
+ * If you are using SDL's 2D rendering API, there is an equivalent call
+ * to load images directly into an SDL_Texture for use by the GPU without
+ * using a software surface: call IMG_LoadTexture_RW() instead.
+ *
+ * When done with the returned surface, the app should dispose of it with
+ * a call to SDL_FreeSurface().
+ *
+ * \param src an SDL_RWops that data will be read from.
+ * \param freesrc non-zero to close/free the SDL_RWops before returning, zero
+ *                to leave it open.
+ * \returns a new SDL surface, or NULL on error.
+ *
+ * \since This function is available since SDL_image 2.0.0.
  *
  * \sa IMG_Load
  * \sa IMG_LoadTyped_RW
@@ -266,26 +349,81 @@ extern DECLSPEC SDL_Surface * SDLCALL IMG_Load_RW(SDL_RWops *src, int freesrc);
 #if SDL_VERSION_ATLEAST(2,0,0)
 
 /**
- * Load an image directly into a render texture.
+ * Load an image from a filesystem path into a GPU texture.
  *
- * \param renderer SDL Render
- * \param file image file name
- * \returns SDL Texture, or NULL on error.
+ * An SDL_Texture represents an image in GPU memory, usable by SDL's 2D
+ * Render API. This can be significantly more efficient than using a CPU-bound
+ * SDL_Surface if you don't need to manipulate the image directly after loading
+ * it.
+ *
+ * If the loaded image has transparency or a colorkey, a texture with an
+ * alpha channel will be created. Otherwise, SDL_image will attempt to
+ * create an SDL_Texture in the most format that most reasonably
+ * represents the image data (but in many cases, this will just end up being
+ * 32-bit RGB or 32-bit RGBA).
+ *
+ * There is a separate function to read files from an SDL_RWops, if you need
+ * an i/o abstraction to provide data from anywhere instead of a simple
+ * filesystem read; that function is IMG_LoadTexture_RW().
+ *
+ * If you would rather decode an image to an SDL_Surface (a buffer of pixels in
+ * CPU memory), call IMG_Load() instead.
+ *
+ * When done with the returned texture, the app should dispose of it with
+ * a call to SDL_DestroyTexture().
+ *
+ * \param renderer the SDL_Renderer to use to create the GPU texture.
+ * \param file a path on the filesystem to load an image from.
+ * \returns a new texture, or NULL on error.
+ *
+ * \since This function is available since SDL_image 2.0.0.
  *
- * \sa IMG_LoadTexture_RW
  * \sa IMG_LoadTextureTyped_RW
+ * \sa IMG_LoadTexture_RW
  * \sa SDL_DestroyTexture
  */
 extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture(SDL_Renderer *renderer, const char *file);
 
 /**
- * Load an image directly into a render texture.
+ * Load an image from an SDL data source into a GPU texture.
  *
- * \param renderer SDL Render
- * \param src RWops
- * \param freesrc can be set so that the RWops is freed after this function is
- *                called
- * \returns SDL Texture, or NULL on error
+ * An SDL_Texture represents an image in GPU memory, usable by SDL's 2D
+ * Render API. This can be significantly more efficient than using a CPU-bound
+ * SDL_Surface if you don't need to manipulate the image directly after loading
+ * it.
+ *
+ * If the loaded image has transparency or a colorkey, a texture with an
+ * alpha channel will be created. Otherwise, SDL_image will attempt to
+ * create an SDL_Texture in the most format that most reasonably
+ * represents the image 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,
+ * whether this function succeeds or not. SDL_image reads everything it needs
+ * from the RWops during this call in any case.
+ *
+ * There is a separate function to read files from disk without having to deal
+ * with SDL_RWops: `IMG_LoadTexture(renderer, "filename.jpg")` will call this
+ * function and manage those details for you, determining the file type from
+ * the filename's extension.
+ *
+ * There is also IMG_LoadTextureTyped_RW(), which is equivalent to this function
+ * except a file extension (like "BMP", "JPG", etc) can be specified, in case
+ * SDL_image cannot autodetect the file format.
+ *
+ * If you would rather decode an image to an SDL_Surface (a buffer of pixels in
+ * CPU memory), call IMG_Load() instead.
+ *
+ * When done with the returned texture, the app should dispose of it with
+ * a call to SDL_DestroyTexture().
+ *
+ * \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
+ *                to leave it open.
+ * \returns a new texture, or NULL on error.
+ *
+ * \since This function is available since SDL_image 2.0.0.
  *
  * \sa IMG_LoadTexture
  * \sa IMG_LoadTextureTyped_RW
@@ -294,14 +432,52 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture(SDL_Renderer *renderer, co
 extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTexture_RW(SDL_Renderer *renderer, SDL_RWops *src, int freesrc);
 
 /**
- * Load an image directly into a render texture.
+ * Load an image from an SDL data source into a GPU texture.
  *
- * \param renderer SDL Render
- * \param src RWops
- * \param freesrc can be set so that the RWops is freed after this function is
- *                called
- * \param type may be one of: "BMP", "GIF", "PNG", etc.
- * \returns SDL Texture, or NULL on error
+ * An SDL_Texture represents an image in GPU memory, usable by SDL's 2D
+ * Render API. This can be significantly more efficient than using a CPU-bound
+ * SDL_Surface if you don't need to manipulate the image directly after loading
+ * it.
+ *
+ * If the loaded image has transparency or a colorkey, a texture with an
+ * alpha channel will be created. Otherwise, SDL_image will attempt to
+ * create an SDL_Texture in the most format that most reasonably
+ * represents the image 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,
+ * whether this function succeeds or not. SDL_image reads everything it needs
+ * from the RWops during this call in any case.
+ *
+ * Even though this function accepts a file type, SDL_image may still try
+ * other decoders that are capable of detecting file type from the contents
+ * of the image data, but may rely on the caller-provided type string for
+ * formats that it cannot autodetect. If `type` is NULL, SDL_image will
+ * rely solely on its ability to guess the format.
+ *
+ * There is a separate function to read files from disk without having to deal
+ * with SDL_RWops: `IMG_LoadTexture("filename.jpg")` will call this function and
+ * manage those details for you, determining the file type from the filename's
+ * extension.
+ *
+ * There is also IMG_LoadTexture_RW(), which is equivalent to this function except
+ * that it will rely on SDL_image to determine what type of data it is loading,
+ * much like passing a NULL for type.
+ *
+ * If you would rather decode an image to an SDL_Surface (a buffer of pixels in
+ * CPU memory), call IMG_LoadTyped_RW() instead.
+ *
+ * When done with the returned texture, the app should dispose of it with
+ * a call to SDL_DestroyTexture().
+ *
+ * \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
+ *                to leave it open.
+ * \param type a filename extension that represent this data ("BMP", "GIF", "PNG", etc).
+ * \returns a new texture, or NULL on error.
+ *
+ * \since This function is available since SDL_image 2.0.0.
  *
  * \sa IMG_LoadTexture
  * \sa IMG_LoadTexture_RW
@@ -311,10 +487,24 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTextureTyped_RW(SDL_Renderer *rend
 #endif /* SDL 2.0 */
 
 /**
- * Functions to detect a file type, given a seekable source
+ * Detect FILETYPE image data on a readable/seekable SDL_RWops.
  *
- * \param src RWops
- * \returns 1 if file type is detected, 0 otherwise
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is FILETYPE data, zero otherwise.
  *
  * \sa IMG_isAVIF
  * \sa IMG_isICO
@@ -336,22 +526,685 @@ extern DECLSPEC SDL_Texture * SDLCALL IMG_LoadTextureTyped_RW(SDL_Renderer *rend
  * \sa IMG_isWEBP
  */
 extern DECLSPEC int SDLCALL IMG_isAVIF(SDL_RWops *src);
+
+/**
+ * Detect ICO image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is ICO data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isICO(SDL_RWops *src);
+
+/**
+ * Detect CUR image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is CUR data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isCUR(SDL_RWops *src);
+
+/**
+ * Detect BMP image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is BMP data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isBMP(SDL_RWops *src);
+
+/**
+ * Detect GIF image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is GIF data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isGIF(SDL_RWops *src);
+
+/**
+ * Detect JPG image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is JPG data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isJPG(SDL_RWops *src);
+
+/**
+ * Detect JXL image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is JXL data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isJXL(SDL_RWops *src);
+
+/**
+ * Detect LBM image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is LBM data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isLBM(SDL_RWops *src);
+
+/**
+ * Detect PCX image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is PCX data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isPCX(SDL_RWops *src);
+
+/**
+ * Detect PNG image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is PNG data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNM
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isPNG(SDL_RWops *src);
+
+/**
+ * Detect PNM image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is PNM data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isSVG
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isPNM(SDL_RWops *src);
+
+/**
+ * Detect SVG image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different IMG_isTYPE function, or load the image without further seeking.
+ *
+ * You do not need to call this function to load data; SDL_image can work to
+ * determine file type in many cases in its standard load functions.
+ *
+ * \param src a seekable/readable SDL_RWops to provide image data.
+ * \returns non-zero if this is SVG data, zero otherwise.
+ *
+ * \sa IMG_isAVIF
+ * \sa IMG_isICO
+ * \sa IMG_isCUR
+ * \sa IMG_isBMP
+ * \sa IMG_isGIF
+ * \sa IMG_isJPG
+ * \sa IMG_isJXL
+ * \sa IMG_isLBM
+ * \sa IMG_isPCX
+ * \sa IMG_isPNG
+ * \sa IMG_isPNM
+ * \sa IMG_isQOI
+ * \sa IMG_isTIF
+ * \sa IMG_isXCF
+ * \sa IMG_isXPM
+ * \sa IMG_isXV
+ * \sa IMG_isWEBP
+ */
 extern DECLSPEC int SDLCALL IMG_isSVG(SDL_RWops *src);
+
+/**
+ * Detect QOI image data on a readable/seekable SDL_RWops.
+ *
+ * This function attempts to determine if a file is a given filetype, reading
+ * the least amount possible from the SDL_RWops (usually a few bytes).
+ *
+ * There is no distinction made between "not the filetype in question" and
+ * basic i/o errors.
+ *
+ * This function will always attempt to seek the RWops back to where it started
+ * when this function was called, but it will not report any errors in doing so,
+ * but assuming seeking works, this means you can immediately use this with
+ * a different

(Patch may be truncated, please check the link at the top of this post.)