set_gfx_mode(3alleg4)

✨ set_gfx_mode — Allegro manual, page set_gfx_mode(3alleg4) ✨

okay bestie so this is a page from the Allegro manual, and it's literally all about switching your screen into graphics mode 💖

🌈 NAME 🌈

set_gfx_mode — sets a graphic video mode. it's part of the Allegro game programming library, periodt.

🎀 SYNOPSIS 🎀

#include <allegro.h>

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

like. five ints. that's it. she's not complicated, she's just powerful 💅

🦋 DESCRIPTION 🦋

So this function switches you into graphics mode. iconic behavior honestly.

The card parameter should usually be one of the Allegro magic drivers (go read the intro of the chapter "Graphics modes" for that) — or peek at the platform-specific docs for the full list of available drivers. slay.

Then w and h are the screen resolution you want, bestie. be specific!

⚠️ heads up: the color depth of the graphic mode has to be specified before you call this function — you do that with set_color_depth(). don't skip that step, i'm begging 😭

The v_w and v_h params specify the minimum virtual screen size, for when you need a big virtual screen for hardware scrolling or page flipping. if you literally do not care about the virtual screen size, set them to zero and move on. zero is your friend 🫶

Now here's the tea 🍵 — when you call set_gfx_mode(), v_w and v_h represent the minimum size of virtual screen that's acceptable for your program. and the range of possible sizes is usually very restricted. Allegro may end up creating a virtual screen that's much larger than the one you requested. the allowed sizes are driver dependent, and some drivers do not allow virtual screens that are larger than the visible screen at all. so no cap: don't assume that whatever you pass will always work. 🙈

In mode-X the virtual width can be any multiple of eight greater than or equal to the physical screen width, and the virtual height will be set accordingly — because the VGA has 256k of vram, the virtual height will be 256*1024/virtual_width. math queen behavior honestly 📐

Currently, using a big virtual screen for page flipping is considered bad practice. 💀 There are platforms which 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 aren't going to use hardware scrolling, you should call set_gfx_mode() with (0,0) as the virtual screen size, and later create the different video pages with create_video_bitmap(). Otherwise your program will be limited to the platforms supporting hardware scrolling. lowkey a big deal.

After you select a graphics mode, the physical and virtual screen sizes can be checked with the macros SCREEN_W, SCREEN_H, VIRTUAL_W, and VIRTUAL_H. vibe check your screen sizes, always ✨

💜 RETURN VALUE 💜

Returns zero on success 🎉

On failure it returns a negative number and stores a description of the problem in allegro_error. so if something's wrong, go read allegro_error — she's telling you what happened, bestie, listen to her 😭

🌸 SEE ALSO 🌸

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

Allegro, version 4.4.3, and this whole page is set_gfx_mode(3alleg4) — that's the source/version and the date-ish footer situation, mwah 💋 go set some gfx modes, you absolute main character 👑💅✨