set_clip_rect(3)

📦 version 4.4.3.1, in fedora 43, fedora 44

💖 set_clip_rect — bestie edition ✨

okay so you're here for set_clip_rect, which is the Allegro game programming library function that sets the clipping rectangle of a bitmap. that's it, that's the vibe. let's get into it 🎀

🌸 SYNOPSIS 🌸

#include <allegro.h>

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

🦋 DESCRIPTION 🦋

so every single bitmap has this lil bestie attached to it called a clipping rectangle, and it's literally just the area of the image that it's OK to draw onto. nothing gets drawn to positions outside of it. nothing. zero. nada. it's giving velvet rope at the club 🚫✨

this function sets the clipping rectangle for the bitmap you hand it. you pass in the coordinates of the top-left and bottom-right corners of the clipping rectangle, in that order. and here's the tea: both of those 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 (33, 33). the corners are in the club, the outside is not 💅

🫶 when does drawing actually happen?? 🫶

drawing operations will be performed (at least partially, bestie, don't panic) on the bitmap as long as both of these are true:

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

if either one of those conditions is not fulfilled, drawing gets turned off for that bitmap. fully off. lights out. like so:

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

that's the classic little trick to just switch drawing off on bmp 😭 iconic honestly

🌈 a note on out-of-bitmap coordinates 🌈

ngl, passing "out-of-bitmap" coordinates is allowed, but they're likely to get altered — which means the coordinates that come back from get_clip_rect() will be different than what you put in. 🙈

but don't stress!! those modifications are guaranteed to preserve the external effect of the clipping rectangle. what does that mean in bestie terms? it means the actual area of the image that it's OK to draw onto does not get modified. the coordinates might glow up differently, but the effect stays exactly the same. periodt. 👑

⭐ SEE ALSO ⭐

go read those next, i'm obsessed with them fr fr 🧚

okay that's the whole page, bestie!! this was brought to you by the <b>Allegro</b> manual, <b>version 4.4.3</b> — mwah, love you, go clip some rectangles 💖✨🎀🦋🌸💅🫶

📦 where this page comes from