SDL_CreateCursor(3)

💖 SDL_CreateCursor — bestie edition 💖

okay so this is a page from the SDL3 FUNCTIONS manual, and yes it's literally called SDL_CreateCursor(3). sit down, grab a strawberry 🍓, we're making a cursor out of raw bits.

---

✨ NAME ✨

SDL_CreateCursor — make a cursor using the bitmap data and mask you hand it (in MSB format, we'll get to that).

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_mouse.h>

SDL_Cursor * SDL_CreateCursor(const Uint8 *data,
                         const Uint8 *mask,
                         int w, int h, int hot_x,
                         int hot_y);

---

🦋 DESCRIPTION 🦋

okay bestie, first thing: mask has got to be in MSB (Most Significant Bit) format. no negotiating.

second thing: your cursor width, that's w, must be a multiple of 8 bits. the way that it just has to be. 💅

now the fun part — the cursor comes out in black and white, and it decides which is which based on this little chart right here:

• data=0, mask=1: white
• data=1, mask=1: black
• data=0, mask=0: transparent
• data=1, mask=0: inverted color if possible, black if not.

⚠️ real talk: cursors you make with this function must be freed with SDL_DestroyCursor(). do not ghost them. they will haunt you (leak). 😭

and if you're sitting there like "girl I want a color cursor" — or you wanna build your cursor out of an SDL_Surface — you want SDL_CreateColorCursor(). alternatively you can just hide the cursor and draw your own as part of your game's rendering, but heads up, that gets bound to the framerate. so. lowkey a tradeoff. 🙈

also!! SDL_CreateSystemCursor() exists, and it hands you several readily-available system cursors to pick from. no bit-fiddling required, iconic behavior honestly. 👑

---

🎀 FUNCTION PARAMETERS 🎀

• data — the color value for each pixel of the cursor.
• mask — the mask value for each pixel of the cursor.
• w — the width of the cursor.
• h — the height of the cursor.
• hot_x — the x-axis offset from the left of the cursor image to the mouse x position, in the range of 0 to w - 1.
• hot_y — the y-axis offset from the top of the cursor image to the mouse y position, in the range of 0 to h - 1.

---

⭐ RETURN VALUE ⭐

on success you get a brand new cursor with all the parameters you specified. on failure you get NULL. 😭

if that happens, call SDL_GetError() for more info — she will tell you what went wrong, fr fr.

---

🧵 THREAD SAFETY 🧵

main thread only, bestie. this function should only be called on the main thread. no side quests. 🫶

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0. periodt.

---

👑 SEE ALSO 👑

• SDL_CreateAnimatedCursor(3)
• SDL_CreateColorCursor(3)
• SDL_CreateSystemCursor(3)
• SDL_DestroyCursor(3)
• SDL_SetCursor(3)

---

Simple Directmedia Layer wrote this one, this is SDL 3.4.18, and the page is SDL_CreateCursor(3). mwah, go make something cute 💋✨🎀