set_mouse_cursor_bitmap(3)

✨ set_mouse_cursor_bitmap 💅

okay bestie, so this is a page from the Allegro manual, section 3, and it's literally all about set_mouse_cursor_bitmap — the glow-up function for your mouse cursor's lil picture. 🖱️✨

🎀 SYNOPSIS 🎀

#include <allegro.h>

void set_mouse_cursor_bitmap(int cursor, BITMAP *bmp);

🦋 DESCRIPTION 🦋

so here's the tea ☕: this function swaps out the cursor image Allegro uses if select_mouse_cursor() gets called but like… there's no native operating system cursor it can use. when does that happen? for example, because you didn't call enable_hardware_cursor(). yeah. that one's on you, no cap. 😭

the cursor argument can be one of these icons, and they're all giving very specific energy:

• MOUSE_CURSOR_ALLEGRO
• MOUSE_CURSOR_ARROW
• MOUSE_CURSOR_BUSY
• MOUSE_CURSOR_QUESTION
• MOUSE_CURSOR_EDIT

🚨 but not MOUSE_CURSOR_NONE. do not pass that one. it's not invited to the function. periodt. 🙈

now the bmp argument, and this one's flexible — it can either point to a valid bitmap, or it can be NULL. your choice, bestie, main character decisions only.

• pass a bitmap and Allegro will use that image instead of its own default substitution (that's the fallback for when the operating system's native cursor isn't available). ⚠️ the bitmap must remain available for the duration in which it could be used — so don't free it, don't let it get eaten, keep it alive and thriving.
• pass NULL and Allegro reverts to its default substitutions. back to factory settings, iconic behaviour. 💖

👀 also important: the effect of this function will not be apparent until show_mouse() is called. so if you're sitting there like "why is nothing happening"… girl. call show_mouse(). that's the vibe check.

🌈 SEE ALSO 🌈

• install_mouse(3)
• show_mouse(3)
• set_mouse_sprite(3)
• gfx_capabilities(3)
• enable_hardware_cursor(3)
• show_os_cursor(3)

okay that's the whole page, you ate that fr fr. 🫶 this was written for Allegro, version 4.4.3 — and that's the whole manual entry, slay. 💅🌸