IMG_CreateA...hProperties(3)

💖 NAME 💖

IMG_CreateAnimationDecoderWithProperties — bestie, this is the glow-up function that creates an animation decoder with exactly the properties you hand it. No more, no less. 👑

---

🌸 SYNOPSIS 🌸

#include <SDL3_image/SDL_image.h>

IMG_AnimationDecoder * IMG_CreateAnimationDecoderWithProperties(SDL_PropertiesID props);

#define IMG_PROP_ANIMATION_DECODER_CREATE_FILENAME_STRING                "SDL_image.animation_decoder.create.filename"
#define IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_POINTER               "SDL_image.animation_decoder.create.iostream"
#define IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN     "SDL_image.animation_decoder.create.iostream.autoclose"
#define IMG_PROP_ANIMATION_DECODER_CREATE_TYPE_STRING                    "SDL_image.animation_decoder.create.type"
#define IMG_PROP_ANIMATION_DECODER_CREATE_TIMEBASE_NUMERATOR_NUMBER      "SDL_image.animation_decoder.create.timebase.numerator"
#define IMG_PROP_ANIMATION_DECODER_CREATE_TIMEBASE_DENOMINATOR_NUMBER    "SDL_image.animation_decoder.create.timebase.denominator"

#define IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_MAX_THREADS_NUMBER        "SDL_image.animation_decoder.create.avif.max_threads"
#define IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_ALLOW_INCREMENTAL_BOOLEAN "SDL_image.animation_decoder.create.avif.allow_incremental"
#define IMG_PROP_ANIMATION_DECODER_CREATE_AVIF_ALLOW_PROGRESSIVE_BOOLEAN "SDL_image.animation_decoder.create.avif.allow_progressive"
#define IMG_PROP_ANIMATION_DECODER_CREATE_GIF_TRANSPARENT_COLOR_INDEX_NUMBER "SDL_image.animation_encoder.create.gif.transparent_color_index"
#define IMG_PROP_ANIMATION_DECODER_CREATE_GIF_NUM_COLORS_NUMBER          "SDL_image.animation_encoder.create.gif.num_colors"

ngl those #define lines are long, but copy them character for character, bestie. Even the ones whose strings say encoder — that's literally what's written up there, so write it exactly like that. 👀

---

🎀 DESCRIPTION 🎀

okay so first things first, here's the tea on which animation types are supported right now:

• ANI
• APNG
• AVIFS
• GIF
• WEBP

and these are the properties you can pass in, the whole roster:

• IMG_PROP_ANIMATION_DECODER_CREATE_FILENAME_STRING — the file to load, if an SDL_IOStream isn't being used. This one is required if IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_POINTER isn't set. pick one, bestie, you can't have neither. 💅
• IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_POINTER — an SDL_IOStream containing a series of images. this one should not be closed until the animation decoder is closed, fr fr. and it's required if IMG_PROP_ANIMATION_DECODER_CREATE_FILENAME_STRING isn't set.
• IMG_PROP_ANIMATION_DECODER_CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN — true if closing the animation decoder should also close the associated SDL_IOStream. set it and forget it energy. ✨
• IMG_PROP_ANIMATION_DECODER_CREATE_TYPE_STRING — the input file type, like "webp". it defaults to the file extension if IMG_PROP_ANIMATION_DECODER_CREATE_FILENAME_STRING is set. so if you set the filename, she already knows. 🦋

---

🫶 FUNCTION PARAMETERS 🫶

• props — the properties of the animation decoder. that's the whole assignment.

---

😭 RETURN VALUE 😭

Returns a new IMG_AnimationDecoder, or NULL on failure — and if it's NULL, call SDL_GetError() for more information. no guessing, bestie, ask her directly.

---

🌈 AVAILABILITY 🌈

This function is available since SDL_image 3.4.0. so if you're on something older, it's giving ancient. 💀

---

👑 SEE ALSO 👑

• IMG_CreateAnimationDecoder(3)
• IMG_CreateAnimationDecoder_IO(3)
• IMG_GetAnimationDecoderFrame(3)
• IMG_ResetAnimationDecoder(3)
• IMG_CloseAnimationDecoder(3)

---

that's the whole page, and you ate it up. this one's from the SDL_image manual, version SDL_image 3.4.8, filed under IMG_CreateA...hProperties(3). go forth and decode, main character. 🎀💖✨