IMG_GetAnim...ecoderFrame(3)

💖 IMG_GetAnimationDecoderFrame 💖

okay bestie, so this one lives in the SDL_image3 manual, in the FUNCTIONS section, and it's literally the little engine that could for pulling frames out of an animation. it's giving "next frame please" energy. 🎬✨

---

🌸 NAME 🌸

IMG_GetAnimationDecoderFrame — get the next frame in an animation decoder. yes, the next one. one at a time. we are patient and we are slaying. 💅

---

🦋 SYNOPSIS 🦋

#include <SDL3_image/SDL_image.h>

bool IMG_GetAnimationDecoderFrame(IMG_AnimationDecoder *decoder, SDL_Surface **frame, Uint64 *duration);

like. look at that signature. gorgeous. iconic. no notes. 😭💜

---

✨ DESCRIPTION ✨

so basically? this function decodes the next frame in the animation decoder and hands it back to you as an SDL_Surface. that's it, that's the whole job, and it does it so well.

⚠️ bestie listen: the surface it gives you is yours now, and you should free it with SDL_FreeSurface() when you're done with it. do not leave it lying around. that's a memory leak and we do not do those in this house. 🚮💖

now here's the part you actually need to know, and it's a little sneaky. if the animation decoder has no more frames or an error happened while decoding, this function returns false. and like, both of those return false, so how do you tell them apart?? 😳

you call SDL_GetError(). periodt.

• if SDL_GetError() returns an empty string → that means there are simply no more available frames. you've reached the end. the animation said "that's all folks". 🎀
• if SDL_GetError() returns a valid string → that means the decoding actually failed. something went wrong. 🚨

so yeah, don't just see false and panic — check the error string, it will tell you which vibe you're in. 🔍

---

🎀 FUNCTION PARAMETERS 🎀

• decoder — the animation decoder. the main character of this whole operation. 👑
• frame — a pointer that gets filled in with the SDL_Surface for the next frame in the animation. it's an out-param, so it's gonna write the frame into your pointer. 🖼️
• duration — the duration of the frame. usually this is in milliseconds, but ngl it can be other units if the IMG_PROP_ANIMATION_DECODER_CREATE_TIMEBASE_DENOMINATOR_NUMBER property is set when you create the decoder. so like, check your timebase before you assume. iykyk. ⏱️

---

💀 RETURN VALUE 💀

returns true on success. 🎉 returns false on failure and also when no more frames are available. yeah. same value, two meanings, it's messy but we deal.

if you need more info, call IMG_GetAnimationDecoderStatus() or SDL_GetError(). they will fill you in. 🫶

---

🌈 AVAILABILITY 🌈

this function is available since SDL_image 3.4.0. so if you're on anything older... bestie. upgrade. 😭

---

👑 SEE ALSO 👑

• IMG_CreateAnimationDecoder(3)
• IMG_CreateAnimationDecoder_IO(3)
• IMG_CreateAnimationDecoderWithProperties(3)
• IMG_GetAnimationDecoderStatus(3)
• IMG_ResetAnimationDecoder(3)
• IMG_CloseAnimationDecoder(3)

the whole friend group fr fr 🫂💖

---

and that's the page!! written by the SDL_image girlies, version SDL_image 3.4.8, and yeah it's giving classic manpage date energy but we're keeping it cute anyway. go decode some frames, bestie, you're gonna eat. 💅✨🎀