IMG_CreateA...hProperties(3)

💖 IMG_CreateA...hProperties — SDL_image3 FUNCTIONS 💖

okay bestie, sit down, hydrate, because we're about to create an animation encoder with the specified properties and honestly? it's giving main character energy. this is the page for IMG_CreateAnimationEncoderWithProperties(3) from the SDL_image3 family of functions. no cap, let's get into it. 🎀

---

✨ SYNOPSIS ✨

#include <SDL3_image/SDL_image.h>

IMG_AnimationEncoder * IMG_CreateAnimationEncoderWithProperties(SDL_PropertiesID props);

and now the property name macros, which you literally just pass as strings when you build your SDL_PropertiesID. here they all are, exactly as written, do not touch a single character:

#define IMG_PROP_ANIMATION_ENCODER_CREATE_FILENAME_STRING                "SDL_image.animation_encoder.create.filename"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_POINTER               "SDL_image.animation_encoder.create.iostream"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN     "SDL_image.animation_encoder.create.iostream.autoclose"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_TYPE_STRING                    "SDL_image.animation_encoder.create.type"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_QUALITY_NUMBER                 "SDL_image.animation_encoder.create.quality"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_TIMEBASE_NUMERATOR_NUMBER      "SDL_image.animation_encoder.create.timebase.numerator"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_TIMEBASE_DENOMINATOR_NUMBER    "SDL_image.animation_encoder.create.timebase.denominator"

#define IMG_PROP_ANIMATION_ENCODER_CREATE_AVIF_MAX_THREADS_NUMBER        "SDL_image.animation_encoder.create.avif.max_threads"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_AVIF_KEYFRAME_INTERVAL_NUMBER  "SDL_image.animation_encoder.create.avif.keyframe_interval"
#define IMG_PROP_ANIMATION_ENCODER_CREATE_GIF_USE_LUT_BOOLEAN            "SDL_image.animation_encoder.create.gif.use_lut"

---

🦋 DESCRIPTION 🦋

so like. this function makes you an animation encoder. you hand it a bag of properties, it hands you back a shiny IMG_AnimationEncoder *. the vibes are immaculate.

🌈 the animation types we currently support

these are the ones that are, as of right now, supported. periodt.

• ANI
• APNG
• AVIFS
• GIF
• WEBP

💅 the supported properties

okay here's the actual tea. these are the properties you can set, and what each one does:

• IMG_PROP_ANIMATION_ENCODER_CREATE_FILENAME_STRING — the file to save, if an SDL_IOStream isn't being used. this one is required if IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_POINTER isn't set. so like, pick one of them, bestie, you can't have neither. 😭
• IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_POINTER — an SDL_IOStream that will be used to save the stream. it should not be closed until the animation encoder is closed. this is required if IMG_PROP_ANIMATION_ENCODER_CREATE_FILENAME_STRING isn't set. again: one or the other, not zero of them. 🙈
• IMG_PROP_ANIMATION_ENCODER_CREATE_IOSTREAM_AUTOCLOSE_BOOLEAN — true if closing the animation encoder should also close the associated SDL_IOStream. set it and forget it, honestly.
• IMG_PROP_ANIMATION_ENCODER_CREATE_TYPE_STRING — the output file type, e.g. "webp". defaults to the file extension if IMG_PROP_ANIMATION_ENCODER_CREATE_FILENAME_STRING is set. she's smart, she can figure it out. 👑
• IMG_PROP_ANIMATION_ENCODER_CREATE_QUALITY_NUMBER — the compression quality, in the range of 0 to 100. the higher the number, the higher the quality and the file size. this defaults to a balanced value for compression and quality. so like, it already ate, you don't have to micromanage it. ✨
• IMG_PROP_ANIMATION_ENCODER_CREATE_TIMEBASE_NUMERATOR_NUMBER — the numerator of the fraction used to multiply the pts to convert it to seconds. this defaults to 1.
• IMG_PROP_ANIMATION_ENCODER_CREATE_TIMEBASE_DENOMINATOR_NUMBER — the denominator of the fraction used to multiply the pts to convert it to seconds. this defaults to 1000.

---

🌸 FUNCTION PARAMETERS 🌸

• props — the properties of the animation encoder. that's it. that's the whole argument. one (1) singular vibe bag. 🫶

---

⭐ RETURN VALUE ⭐

Returns a new IMG_AnimationEncoder, or NULL on failure. and if you get a NULL? don't panic, just call SDL_GetError() for more information. she will tell you what went wrong, i promise. 💀

---

🧚 AVAILABILITY 🧚

This function is available since SDL_image 3.4.0. if you're on something older, bestie, it's not there. upgrade era.

---

👑 SEE ALSO 👑

go read these too, they're all in the same friend group:

• IMG_CreateAnimationEncoder(3)
• IMG_CreateAnimationEncoder_IO(3)
• IMG_AddAnimationEncoderFrame(3)
• IMG_CloseAnimationEncoder(3)

---

and that's the whole page, bestie!! this came to you from SDL_image, version 3.4.8, and yes the header up top said IMG_CreateA...hProperties(3) because the name is long and the terminal said "no <3". go make something iconic with it. mwah. 💖✨🎀