request_video_bitmap(3alleg4)

✨ request_video_bitmap ✨

okay bestie, gather round, because this one is from the Allegro manual (yes, the game programming library, we love her) and it's all about that triple buffering lifestyle 💅

💖 NAME 💖

request_video_bitmap — Triple buffering page flip request. Allegro game programming library. that's it, that's the name, no notes ✨

🌸 SYNOPSIS 🌸

#include <allegro.h>

int request_video_bitmap(BITMAP *bitmap);

🦋 DESCRIPTION 🦋

so like, this function is your girl for triple buffering 👑

What it does: it requests a page flip to show off the specified video bitmap object, but — and this is the iconic part — it returns immediately instead of standing around waiting for a retrace. no waiting, no blocking, we are booked and busy fr fr.

So the flip is gonna happen during the next vertical retrace, but you can keep running other code in the meantime like the multitasking main character you are 😌 and then you use the poll_scroll() routine to check when the flip has actually taken place.

🫶 heads up: triple buffering is only possible on certain hardware. go read the comments about request_scroll() for the tea.

Example time, look at her go:

int current_page;
BITMAP *video_page[3];
...
/* Create pages for page flipping */
video_page[0] = create_video_bitmap(SCREEN_W, SCREEN_H);
video_page[1] = create_video_bitmap(SCREEN_W, SCREEN_H);
video_page[2] = create_video_bitmap(SCREEN_W, SCREEN_H);
current_page = 0;
...
/* draw the screen and flip pages */
draw_screen(video_page[current_page]);
do {
} while (poll_scroll());
request_video_bitmap(video_page[current_page]);
current_page = (current_page+1)%3;
...

the way that current_page = (current_page+1)%3; is doing modular arithmetic and eating every single time 😭💖

⭐ RETURN VALUE ⭐

• 0 when it works (slay)
• non-zero when it fails (rip)

that's the whole vibe check, zero = success, anything else = not success.

👑 SEE ALSO 👑

• poll_scroll(3alleg4)
• request_scroll(3alleg4)
• gfx_capabilities(3alleg4)
• create_video_bitmap(3alleg4)
• scroll_screen(3alleg4)
• ex3buf(3alleg4)
• exupdate(3alleg4)

and that's the page, bestie!! this was Allegro, version 4.4.3, serving triple-buffered realness. stay flipping, stay iconic, and may your retraces always be vertical 💜✨🎀🦋