install_allegro(3alleg4)

💖 install_allegro — the Allegro manual (3alleg4), bestie edition 💖

okay so real talk, this is install_allegro from the Allegro manual, section 3alleg4, and it's literally the "wake up bestie" button for the whole library. let's get into it 🫶

✨ NAME ✨

install_allegro — Initialise the Allegro library. that's it, that's the whole job. she's the alarm clock of the Allegro universe ⏰

🌸 SYNOPSIS 🌸

#include <allegro.h>

int install_allegro(int system_id, int *errno_ptr, int (*atexit_ptr)());

🦋 DESCRIPTION 🦋

So. This is the one that initialises the Allegro library. You must call either this or allegro_init() before you do literally anything else — with one tiny exception, and that exception is the Unicode routines. That's it. That's the only free pass. Everything else waits its turn, bestie 💅

oh and btw, if you want a text mode that isn't UTF-8, you can set it with set_uformat() before you call this. sneak it in early, she's flexible like that. The other functions that are allowed to be called before this one get explicitly marked in the documentation, like set_config_file() — so if you see a function with the little "yes you can call me first" badge, that's why 🌈

Now the tea on system_id:

• The available system ID codes vary from one platform to another (it's giving "every platform has its own vibe check").
• you will almost always want to pass SYSTEM_AUTODETECT. like, 99% of the time, this is the move. she just figures it out for you, iconic behaviour 👑
• alternatively, SYSTEM_NONE installs a stripped down version of Allegro that won't even try to touch your hardware or do anything platform specific. and why would you want that? because sometimes you just want to manipulate memory bitmaps, no hardware drama. think the text mode datafile tools, or the Windows GDI interfacing functions. low-key perfect for those 🎀

🧚 the two pointer params, pay attention 🧚

The errno_ptr and atexit_ptr parameters should point to the errno variable and the atexit function from your libc. and before you're like "why tho" — it's because when Allegro is linked as a DLL, it doesn't have direct access to your local libc data. so you hand her the addresses, and she's good 💜

atexit_ptr may be NULL, in which case it is your responsibility to call allegro_exit() manually. no cap. don't forget, or you'll be leaving a mess and that's not the vibe 🙈

Example, copy it exactly:

install_allegro(SYSTEM_AUTODETECT, &errno, atexit);

⭐ RETURN VALUE ⭐

This function returns zero on success and non-zero on failure (e.g. no system driver could be used). classic zero-means-good energy ✨

⚠️ Note: in previous versions of Allegro this function would abort on error. so if you're reading old code and wondering why nobody checked the return value... yeah. that's why. it used to just 💀

🔥 SEE ALSO 🔥

• allegro_init(3alleg4)
• allegro_exit(3alleg4)
• set_uformat(3alleg4)
• set_config_file(3alleg4)

and that's the whole page, bestie!! 💖 this came from the Allegro manual, version 4.4.3 — go init something beautiful, call allegro_exit() when you're done, and hydrate 🫶🌸🦋