set_display_switch_mode(3)

💖 set_display_switch_mode(3) 💖

okay bestie so we're deep in the Allegro manual rn and this one is genuinely a big deal — it's set_display_switch_mode, the little function that decides what your program does when somebody ✨tabs away✨ from it. no cap, this one matters.

---

🌸 NAME 🌸

set_display_switch_mode — literally tells Allegro how your program handles background switching 💅

---

🦋 SYNOPSIS 🦋

#include <allegro.h>

int set_display_switch_mode(int mode);

---

✨ DESCRIPTION ✨

so basically this sets how your program should handle getting yeeted into the background when the user tabs away from it 🫶

heads up bestie: not all of the possible modes are supported by every graphics driver on every platform. it's giving "it depends" 😭 so always check what you get back (more on that in RETURN VALUE).

the available modes are, and yes i'm listing every single one:

SWITCH_NONE 🚫

disables switching, periodt. this is the default in single-tasking systems like DOS. it may be supported on other platforms too, but you should use it with caution — because your users will NOT be impressed if they wanna switch away from your program and you simply don't let them 😭 like girl, let them leave.

SWITCH_PAUSE ⏸️

pauses the program whenever it's in the background. execution resumes the second the user switches back to it. this is the default in most fullscreen multitasking environments, for example the Linux console — but not under Windows. okay noted 📝

SWITCH_AMNESIA 🫠

like SWITCH_PAUSE, but this mode doesn't bother to remember the contents of video memory. so the screen — and any video bitmaps you've created — will be erased after the user switches away and then back to your program 💀

ngl this is not a terribly useful mode to have, but it is the default for the fullscreen drivers under Windows, because DirectDraw is too dumb to implement anything better 🙈 (the manpage said it, not me).

SWITCH_BACKGROUND 🌈

the program carries on running in the background, with the screen bitmap temporarily being pointed at a memory buffer for the fullscreen drivers. iconic, but be careful — you must take special care when using this mode, because bad things will happen if the screen bitmap gets changed around when your program isn't expecting it (see below, bestie, i got you).

SWITCH_BACKAMNESIA 🧚

like SWITCH_BACKGROUND, but this mode doesn't bother to remember the contents of video memory (see SWITCH_AMNESIA up there ⬆️). it's again the only mode supported by the fullscreen drivers under Windows that lets the program keep running in the background.

---

⚠️ okay this part is IMPORTANT, read it twice ⚠️ note that you should be very careful when you're using graphics routines in the switching context: you must always call acquire_screen() before the start of any drawing code onto the screen, and not release it until you are completely finished — because the automatic locking mechanism may not be good enough to work when the program runs in the background or has just been raised in the foreground. like, it's just not reliable enough in that situation. so lock it yourself, bestie 🔒

---

💜 RETURN VALUE 💜

returns zero on success — and at the same time it invalidates all callbacks previously registered with set_display_switch_callback(). so like, poof, gone, they're not valid anymore 💅

returns -1 if the requested mode is not currently possible. so yeah, check that return value, fr fr.

---

🎀 SEE ALSO 🎀

• set_display_switch_callback(3)
• get_display_switch_mode(3)
• exmidi(3)
• exsample(3)
• exstream(3)
• exswitch(3)

---

and that's the whole vibe 🦋 this page came to you straight out of Allegro, version 4.4.3, and yeah it's literally titled set_display_switch_mode(3) if you needed the receipts. mwah, go slay your display switching 💅💖