From 2c08c35868196456205b187dbf546b04b7ed2e86 Mon Sep 17 00:00:00 2001
From: "Ryan C. Gordon" <[EMAIL REDACTED]>
Date: Tue, 5 Jul 2022 12:42:30 -0400
Subject: [PATCH] Started updating SDL_image documentation.
---
SDL_image.h | 121 ++++++++++++++++++++++++++++++++++++++++++++++------
1 file changed, 107 insertions(+), 14 deletions(-)
diff --git a/SDL_image.h b/SDL_image.h
index b6f67d06..7a6195d4 100644
--- a/SDL_image.h
+++ b/SDL_image.h
@@ -102,39 +102,132 @@ typedef enum
} IMG_InitFlags;
/**
- * Loads dynamic libraries and prepares them for use.
+ * Initialize SDL_image.
*
- * Flags should be one or more flags from IMG_InitFlags OR'd together.
+ * This function loads dynamic libraries that SDL_image needs, and prepares
+ * them for use. This must be the first function you call in SDL_image, and if
+ * it fails you should not continue with the library.
*
- * \param flags initialization flags
- * \returns flags successfully initialized, or 0 on failure.
+ * Flags should be one or more flags from IMG_InitFlags OR'd together. It
+ * returns the flags successfully initialized, or 0 on failure.
+ *
+ * Currently, these flags are:
+ *
+ * - `_INIT_JPG`
+ * - `_INIT_PNG`
+ * - `_INIT_TIF`
+ * - `_INIT_WEBP`
+ * - `_INIT_JXL`
+ * - `_INIT_AVIF`
+ *
+ * More flags may be added in a future SDL_image release.
+ *
+ * This function may need to load external shared libraries to support various
+ * codecs, which means this function can fail to initialize that support on an
+ * otherwise-reasonable system if the library isn't available; this is not
+ * just a question of exceptional circumstances like running out of memory at
+ * startup!
+ *
+ * Note that you may call this function more than once to initialize with
+ * additional flags. The return value will reflect both new flags that
+ * successfully initialized, and also include flags that had previously been
+ * initialized as well.
+ *
+ * As this will return previously-initialized flags, it's legal to call this
+ * with zero (no flags set). This is a safe no-op that can be used to query
+ * the current initialization state without changing it at all.
+ *
+ * Since this returns previously-initialized flags as well as new ones, and
+ * you can call this with zero, you should not check for a zero return value
+ * to determine an error condition. Instead, you should check to make sure all
+ * the flags you require are set in the return value. If you have a game
+ * with data in a specific format, this might be a fatal error. If you're a
+ * generic image displaying app, perhaps you are fine with only having JPG and
+ * PNG support and can live without WEBP, even if you request support for
+ * everything.
+ *
+ * Unlike other SDL satellite libraries, calls to IMG_Init do not stack; a
+ * single call to IMG_Quit() will deinitialize everything and does not have to
+ * be paired with a matching IMG_Init call. For that reason, it's considered
+ * best practices to have a single IMG_Init and IMG_Quit call in your program.
+ * While this isn't required, be aware of the risks of deviating from that
+ * behavior.
+ *
+ * After initializing SDL_image, the app may begin to load images into
+ * SDL_Surfaces or SDL_Textures.
+ *
+ * \param flags initialization flags, OR'd together.
+ * \returns all currently initialized flags.
+ *
+ * \since This function is available since SDL_image 2.0.0.
*
* \sa IMG_Quit
- * \sa IMG_InitFlags
- * \sa IMG_Load
- * \sa IMG_LoadTexture
*/
extern DECLSPEC int SDLCALL IMG_Init(int flags);
/**
- * Unloads libraries loaded with IMG_Init.
+ * Deinitialize SDL_image.
+ *
+ * This should be the last function you call in SDL_image, after freeing all
+ * other resources. This will unload any shared libraries it is using for
+ * various codecs.
+ *
+ * After this call, a call to IMG_Init(0) will return 0 (no codecs loaded).
+ *
+ * You can safely call IMG_Init() to reload various codec support after this
+ * call.
+ *
+ * Unlike other SDL satellite libraries, calls to IMG_Init do not stack; a
+ * single call to IMG_Quit() will deinitialize everything and does not have to
+ * be paired with a matching IMG_Init call. For that reason, it's considered
+ * best practices to have a single IMG_Init and IMG_Quit call in your program.
+ * While this isn't required, be aware of the risks of deviating from that
+ * behavior.
+ *
+ * \since This function is available since SDL_image 2.0.0.
*
* \sa IMG_Init
*/
extern DECLSPEC void SDLCALL IMG_Quit(void);
/**
- * Load an image from an SDL data source.
+ * Load an image from an SDL data source into a software surface.
+ *
+ * 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.
+ *
+ * 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.
*
* 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);
*
- * \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 surface, or NULL on error.
+ * If `freesrc` is non-zero, the RWops will be closed before returning,
+ * whether this function succeeds or not. SDL_mixer 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_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.
+ *
+ * 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.
+ * \param type a filename extension that represent this data ("BMP", "GIF", "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).
*
* \sa IMG_Load
* \sa IMG_Load_RW