SDL_CreateColorCursor(3)

💖 SDL_CreateColorCursor — like, the color cursor maker 💖

okay bestie, gather round, because this one lives in the SDL3 FUNCTIONS section of the manual and it's literally the glow-up your mouse pointer has been waiting for. Say hi to SDL_CreateColorCursor(3). 🦋

---

✨ NAME ✨

SDL_CreateColorCursor — Create a color cursor.

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_mouse.h>

SDL_Cursor * SDL_CreateColorCursor(SDL_Surface *surface,
                                   int hot_x,
                                   int hot_y);

---

🎀 DESCRIPTION 🎀

So here's the tea, and it's giving high-DPI main character energy. If you hand this function a surface that's got alternate representations added onto it via SDL_AddSurfaceAlternateImage(), then that surface is the one that gets interpreted as the content for 100% display scale. Meanwhile the alternate representations get used for high DPI situations — but only if SDL_HINT_MOUSE_DPI_SCALE_CURSORS is enabled. iykyk. 👑

Example time, because examples ate: if your original surface is 32x32, then on a 2x macOS display, or a 200% display scale on Windows, a 64x64 version of the image will be used — if one's available. ✨

And if a matching version of the image isn't available? No worries, it's not a crisis. The closest larger size image will be downscaled to the appropriate size and used instead, if available. And if even that's not available? Then the closest smaller image gets upscaled and used instead. Adaptive queen behavior fr fr. 💅

---

🫶 FUNCTION PARAMETERS 🫶

• surface — an SDL_Surface structure representing the cursor image. Like, the actual picture of your cursor. 🖼️
• hot_x — the x position of the cursor hot spot. This is the pixel that's actually "clicking", so pick wisely bestie. 🎯
• hot_y — the y position of the cursor hot spot. Same deal, vertical edition. 🎯

---

⭐ RETURN VALUE ⭐

Returns the new cursor on success, or NULL on failure. 😭 And if it fails, call SDL_GetError() for more information — she will tell you what went wrong, no gatekeeping.

---

💀 THREAD SAFETY 💀

This function should only be called on the main thread. No sneaking it onto a worker thread, bestie, I'm serious. 🚫🧵

---

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. So if you're on something older, it's not you, it's the version. 🙈

---

👑 SEE ALSO 👑

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

---

and that's the whole page, periodt. 💅 this icon was brought to you by Simple Directmedia Layer, running on SDL 3.4.18 — same energy, same date stamp, just with way better vibes. go make something cute with it, bestie. 🎀✨🦋💖