screen(3alleg4)

💖 screen 💖

okay bestie, so this is a page from the Allegro manual — the game programming library — and today's main character is screen. yes, lowercase, yes, iconic. let's go 🫶

✨ NAME ✨

screen — the global pointer to the screen hardware video memory. Allegro game programming library. she's famous, she's everywhere, she's literally the whole display. 👑

🌸 SYNOPSIS 🌸

#include <allegro.h>

extern BITMAP *screen;

that's it. that's the girl. one pointer, zero drama (well, mostly).

🦋 DESCRIPTION 🦋

so screen is a global pointer to a bitmap, sized VIRTUAL_W x VIRTUAL_H. it gets created for you by set_gfx_mode(), and it represents the hardware video memory. periodt. ✨

here's the tea though — only a part of that bitmap is actually visible, and that visible part is sized SCREEN_W x SCREEN_H. normally it's the top-left corner of the bigger virtual screen, so if you're not into hardware scrolling or page flipping, you can literally just ignore the extra invisible virtual size of the bitmap. not your problem, bestie. 💅

want to move that visible window around to other parts of the screen bitmap? call scroll_screen(). easy.

⚠️ and listen — initially the clipping rectangle is limited to the physical screen size. so if you wanna draw onto a larger virtual screen space outside that rectangle, you're gonna have to adjust the clipping yourself. no shortcuts, no cap.

🎀 examples, because we love a visual 🎀

for example, to draw a pixel onto the screen you would write:

putpixel(screen, x, y, color);

or, if you wanna implement a double-buffered system:

/* Make a bitmap in RAM. */
BITMAP *bmp = create_bitmap(320, 200);
/* Clean the memory bitmap. */
clear_bitmap(bmp);
/* Draw onto the memory bitmap. */
putpixel(bmp, x, y, color);
/* Copy it to the screen. */
blit(bmp, screen, 0, 0, 0, 0, 320, 200);

like. hello?? blit to screen and suddenly you're on the actual display. main character energy fr fr. 🔥

🚨 the warnings section (read this, i'm begging) 🚨

Warning: be very careful when using this pointer at the same time as any bitmaps created by the create_video_bitmap() function — go read the description of that function for the more detailed info, she explains it better than i can. 🙈

and never — like, never never — try to destroy screen with destroy_bitmap(). do not do it. it is not yours to destroy. she's the screen. you're just living in it. 😭

🌈 SEE ALSO 🌈

• set_gfx_mode(3alleg4)
• is_screen_bitmap(3alleg4)
• create_video_bitmap(3alleg4)
• scroll_screen(3alleg4)

go read those too, they're all connected, iykyk 💜

okay that's the whole page, mwah 💋 this was Allegro, version 4.4.3, and yes this little love letter is signed screen(3alleg4) — take care of her, she's holding up your entire window. bye bestie!! 🎀✨