blit(3)

✨ NAME ✨

blit — copies a rectangular area from one bitmap to another 💖 (part of the Allegro game programming library, bestie, yes that Allegro).

🌸 SYNOPSIS 🌸

#include <allegro.h>

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

🦋 DESCRIPTION 🦋

Okay so here's the tea: blit() takes a rectangle out of the source bitmap and drops it into the dest bitmap. source_x and source_y are the top left corner of the chunk you're grabbing from the source, and dest_x and dest_y are where that same corner lands in the destination. Match made in heaven fr fr.

It respects the destination clipping rectangle — so it's not gonna yeet pixels outside the bounds — and it will also clip if you try to blit from areas outside the source bitmap. Very polite of it honestly. Here's the example:

BITMAP *bmp;
...
/* Blit src on the screen. */
blit(bmp, screen, 0, 0, 0, 0, bmp->w, bmp->h);

/* Now copy a chunk to a corner, slightly outside. /*
blit(screen, screen, 100, 100, -10, -10, 25, 30);

You can blit between any parts of any two bitmaps, even when the two memory areas overlap (ie. source and dest are the same, or one is a sub-bitmap of the other). Iconic flexibility, but listen — plot twist 😭 — a lot of SVGA cards don't have separate read and write banks, which means blitting from one part of the screen to another needs a temporary bitmap in memory. Which is extremely slow. So as a general rule, bestie, avoid blitting from the screen onto itself in SVGA modes. It's giving snail. 🐌

In mode-X though? Different story, and it's kinda slay. Blitting from one part of the screen to another can be significantly faster than blitting from memory onto the screen — as long as source and dest are correctly aligned with each other. Copying between overlapping screen rectangles is slow, but if the areas don't overlap, and if they have the same plane alignment (ie. (source_x%4) == (dest_x%4)), the VGA latch registers can be used for a very fast data transfer. To take advantage of this, in mode-X it's often worth storing tile graphics in a hidden area of video memory (using a large virtual screen) and blitting them from there onto the visible part of the screen. Chef's kiss. 👑

If the GFX_HW_VRAM_BLIT bit in the gfx_capabilities flag is set, the current driver supports hardware accelerated blits from one part of the screen onto another. That is extremely fast, so when this flag is set it may be worth storing some of your more frequently used graphics in an offscreen portion of the video memory. Free real estate, go off. 🔥

And the plot twist that makes blit() the main character: unlike most of the graphics routines, it allows the source and destination bitmaps to be of different color depths, so you can use it to convert images from one pixel format to another. When that happens, the behavior is affected by the COLORCONV_KEEP_TRANS and COLORCONV_DITHER* flags of the current color conversion mode — peep set_color_conversion() for more info. 🎀

💜 SEE ALSO 💜

• masked_blit(3)
• stretch_blit(3)
• draw_sprite(3)
• gfx_capabilities(3)
• set_color_conversion(3)

And that's the whole vibe, bestie — this was blit(3) from the Allegro manual, brought to you by Allegro version 4.4.3. Go forth and copy pixels, you absolute legend. 💅✨🫶