masked_blit(3alleg4)

💖 masked_blit — the Allegro manual, but make it a group chat 💖

okay so bestie, this is a page from the Allegro manual — masked_blit(3alleg4), the Copies a rectangle skipping pixels with the mask color one. it lives in the Allegro game programming library and honestly? it's giving "I just want my sprite on the screen without the ugly box around it" energy. iconic. let's go. 🦋

✨ NAME ✨

masked_blit — copies a rectangle, but skips the pixels that have the mask color. part of the Allegro game programming library, no cap.

✨ SYNOPSIS ✨

#include <allegro.h>

void masked_blit(BITMAP *source, BITMAP *dest, int source_x, int
source_y, int dest_x, int dest_y, int width, int height);

like yes, that's eight arguments, she's high maintenance but she delivers. 💅

✨ DESCRIPTION ✨

so, masked_blit() is literally blit()'s cooler sibling. same energy, one glow-up: it skips transparent pixels, so your sprite doesn't drag a big fat rectangle of background around with it. 🌈

what counts as "transparent"? the mask color, which is:

• a zero in 256-color modes
• bright pink for truecolor data (that's maximum red and blue, zero green — remember it, it comes up in trivia night)

it also requires the source and dest bitmaps to be of the same color depth, so don't be mixing vibes.

and the source and destination regions must not overlap. not a suggestion. not a soft launch. they cannot overlap, periodt. 💀

here's the example, verbatim, because she ate:

BITMAP *hud_overlay;
...
/* Paint hud overlay on the screen. */
masked_blit(hud_overlay, screen, 0, 0, 0, 0,
            hud_overlay->w, hud_overlay->h);

okay now the fun part. if the GFX_HW_VRAM_BLIT_MASKED bit in the gfx_capabilities flag is set, that means your current driver supports hardware accelerated masked blits from one part of the screen onto another. and bestie, that is extremely fast. 🔥 so when that flag is set, it may genuinely be worth storing some of your more frequently used sprites in an offscreen portion of the video memory. treat yourself.

⚠️ Warning, and I need you to actually read this one: if the hardware acceleration flag is not set, masked_blit() will not work correctly when used with a source image in system or video memory — so the latter must be a memory bitmap. that's not me being dramatic, that's just the facts. 😭

✨ SEE ALSO ✨

• blit(3alleg4)
• masked_stretch_blit(3alleg4)
• draw_sprite(3alleg4)
• bitmap_mask_color(3alleg4)
• ex12bit(3alleg4)
• expat(3alleg4)

go read them, they're all part of the same friend group 🫶

and that's the whole page, bestie! this one came from Allegro, version 4.4.3, and it's filed under the name masked_blit(3alleg4) — mwah, no notes, go blit something pretty 💖✨🎀