set_gfx_mode(3)

💖 set_gfx_mode(3) 💖

okay bestie, welcome to the Allegro manual, we're doing graphics modes today and honestly? iconic.

---

✨ NAME ✨

set_gfx_mode — sets a graphic video mode. it's the Allegro game programming library, she's a legend, she's been doing this since forever. 🎀

---

🌈 SYNOPSIS 🌈

#include <allegro.h>

int set_gfx_mode(int card, int w, int h, int v_w, int v_h);

---

👑 DESCRIPTION 👑

So like. This function switches you into graphics mode. That's the whole vibe. 🦋

The card parameter should usually be one of the Allegro magic drivers (go read the intro of the chapter called "Graphics modes"), or you can peek at the platform specific documentation for a whole list of the drivers that exist. Then w and h are you telling Allegro what screen resolution you want. 💅

🚨 bestie listen — the color depth of the graphic mode has to be set before you call this function, and you do that with set_color_depth(). no color depth no service.

The v_w and v_h parameters are the minimum virtual screen size. You'd want those if you need a big virtual screen for hardware scrolling or page flipping. And if you literally do not care about virtual screen size at all? Set them to zero. done. 🍓

When you call set_gfx_mode(), v_w and v_h are representing the minimum size of virtual screen that your program will accept. But here's the tea: the range of possible sizes is usually very restricted, and Allegro might just go ahead and create a virtual screen much larger than the one you asked for. 🙈 Allowed sizes are driver dependent, and some drivers don't allow virtual screens bigger than the visible screen at all — so do not assume that whatever you pass in will always work. fr fr.

In mode-X specifically, the virtual width can be any multiple of eight that's greater than or equal to the physical screen width, and the virtual height gets set accordingly (the VGA has 256k of vram, so the virtual height will be 256*1024/virtual_width). math is math. ✨

Currently, using a big virtual screen for page flipping is considered bad practice. 😭 There are platforms that don't support virtual screens bigger than the physical screen but can create different video pages to flip back and forth. Which means: if you want page flipping and you're not gonna use hardware scrolling, you should call set_gfx_mode() with (0,0) as the virtual screen size, and then later create the different video pages with create_video_bitmap(). Otherwise your program gets limited to only the platforms that support hardware scrolling. 💀

Once you've selected a graphics mode, you can check the physical and virtual screen sizes with the macros SCREEN_W, SCREEN_H, VIRTUAL_W, and VIRTUAL_H. vibe check complete. 🔥

---

🫶 RETURN VALUE 🫶

Returns zero on success. 🎉 On failure it returns a negative number and stores a description of the problem in allegro_error. so check your allegro_error, bestie, she's telling you what went wrong. 😤

---

⭐ SEE ALSO ⭐

• set_color_depth(3)
• request_refresh_rate(3)
• screen(3)
• gfx_capabilities(3)
• allegro_error(3)
• create_video_bitmap(3)
• get_desktop_resolution(3)
• SCREEN_W(3)
• SCREEN_H(3)
• VIRTUAL_W(3)
• VIRTUAL_H(3)

---

k bye that's the page!! this was Allegro version 4.4.3, manual section set_gfx_mode(3), and honestly she ate. 💅✨🦋 no cap, go set some gfx modes bestie, you got this. 👑💖