set_clip_rect(3alleg4)

✨ set_clip_rect ✨

okay bestie, welcome to the Allegro manual 💖 this one's about set_clip_rect — the function that sets the clipping rectangle of a bitmap. yes, the Allegro game programming library, we're in it, we're thriving 🌸

🎀 NAME 🎀

set_clip_rect — sets the clipping rectangle of a bitmap. it's giving Allegro game programming library energy, no cap 💅

🦋 SYNOPSIS 🦋

#include <allegro.h>

void set_clip_rect(BITMAP *bitmap, int x1, int y1, int x2, int y2);

💜 DESCRIPTION 💜

so literally every bitmap has its own lil clipping rectangle, and that rectangle is the area of the image that it is OK to draw onto. anything outside that space? not getting drawn. at all. the vibe check is strict 🚫✨

this function sets the clipping rectangle for the bitmap you hand it. you pass the coordinates of the top-left corner and the bottom-right corner, in that exact order, and here's the iconic part: both corners are inclusive. so like,

set_clip_rect(bitmap, 16, 16, 32, 32);

will let you draw to (16, 16) and (32, 32), but not to (15, 15) and not to (33, 33). inclusive means inclusive, periodt 👑

🔥 when drawing actually happens 🔥

drawing operations will be performed (at least partially) on the bitmap as long as:

1. the first coordinates of its clipping rectangle are not greater than the second coordinates, and
2. its intersection with the actual image is non-empty

if either of those two conditions is not fulfilled, drawing gets turned off for that bitmap. like, fully off. for example:

set_clip_rect(bmp, 0, 0, -1, -1); /* disable drawing on bmp */

see that? that's the move. drawing on bmp? cancelled 🙈

🌈 the out-of-bitmap thing (important, bestie) 🌈

passing "out-of-bitmap" coordinates is allowed, but they are likely to be altered — which means the coordinates you get back from get_clip_rect() will be different. don't panic though, because those modifications are guaranteed to preserve the external effect of the clipping rectangle. translation: the actual area of the image that it's OK to draw onto does not change. the numbers might shift, the effect does not. fr fr 💯

👑 SEE ALSO 👑

• get_clip_rect(3alleg4)
• add_clip_rect(3alleg4)
• set_clip_state(3alleg4)
• get_clip_state(3alleg4)
• ex12bit(3alleg4)
• excamera(3alleg4)

go read those next, i'm obsessed with this whole family honestly 🫶

and that's the whole page, bestie!! this was Allegro, version 4.4.3, and the page is set_clip_rect(3alleg4) — tysm for reading, mwah, go clip responsibly 💖🎀✨