SDL_CreateAnimatedCursor(3)

✨ SDL_CreateAnimatedCursor ✨

okay bestie, so this is a page from the SDL3 FUNCTIONS manual and it's literally all about making your mouse cursor move. yes. animated. cursor. the little arrow gets a glow-up 💅

---

🌸 NAME 🌸

SDL_CreateAnimatedCursor — create an animated color cursor. that's it, that's the whole vibe 🎀

---

🦋 SYNOPSIS 🦋

#include <SDL3/SDL_mouse.h>

SDL_Cursor* SDL_CreateAnimatedCursor(SDL_CursorFrameInfo *frames,
                                     int frame_count,
                                     int hot_x,
                                     int hot_y);

---

💖 DESCRIPTION 💖

so the tea is: animated cursors are made of a sequential array of frames, and you specify them as surfaces plus durations inside an array of SDL_CursorFrameInfo structs. like a little flipbook but for your pointer. iconic honestly 🫶

the hot spot coordinates are universal to all frames — one hot spot to rule them all — and ngl all the frames have to have the same dimensions. no mixing sizes, bestie, it's giving consistency queen 👑

frame durations are specified in milliseconds. and here's the important part: a duration of 0 implies an infinite frame time, and the animation will stop on that frame. so if you want a one-shot animation? set the duration of the last frame in the sequence to 0. periodt 💀

🚨 lowkey important: that 0 duration means the animation halts right there. it's not a sneaky little pause, it's the end of the road.

if this function is passed surfaces with alternate representations added with SDL_AddSurfaceAlternateImage(), then those surfaces get interpreted as the content used for 100% display scale, and the alternate representations get used for high DPI situations. for example (and I'm quoting the math here, no cap): if the original surfaces are 32x32, then on a 2x macOS display or 200% display scale on Windows, a 64x64 version of the image will be used, if available. and if a matching version of the image isn't available? the closest larger size image will be downscaled to the appropriate size and be used instead, if available. otherwise, the closest smaller image will be upscaled and be used instead. so it's got a whole backup plan, main character energy fr fr ✨

and if the underlying platform does not support animated cursors, this function will fall back to creating a static color cursor using the first frame in the sequence. so you're never left with nothing, she always shows up 🌈

---

🎀 FUNCTION PARAMETERS 🎀

• frames — an array of cursor images composing the animation. the whole cast, the ensemble 🎬
• frame_count — the number of frames in the sequence. how many besties are in this lineup 💫
• hot_x — the x position of the cursor hot spot. the exact spot where the click actually lands, x edition 📍
• hot_y — the y position of the cursor hot spot. same energy, y axis 📍

---

⭐ RETURN VALUE ⭐

returns the new cursor on success, or NULL on failure. and if it's NULL? call SDL_GetError() for more information — she will tell you what went wrong, just ask her 😭

---

💜 THREAD SAFETY 💜

this function should only be called on the main thread. no side quests, no other threads, this one's a main-thread-only girly 🙈

---

🌟 AVAILABILITY 🌟

this function is available since SDL 3.4.0. so if you're on anything older, bestie, you're not invited to this party 💀

---

🔥 SEE ALSO 🔥

• SDL_AddSurfaceAlternateImage(3)
• SDL_CreateCursor(3)
• SDL_CreateColorCursor(3)
• SDL_CreateSystemCursor(3)
• SDL_DestroyCursor(3)
• SDL_SetCursor(3)

---

and that's the whole page, no notes 💅 this one came to you courtesy of Simple Directmedia Layer, straight from SDL 3.4.18. go make a cursor that slays, bestie 🦋✨💖