al_set_target_bitmap(3alleg5)

💖 al_set_target_bitmap — Allegro 5 API 💖

okay bestie, welcome to the al_set_target_bitmap(3alleg5) page, straight out of the Allegro reference manual. this one's a glow-up for your rendering pipeline, fr fr. let's get into it 🎀

---

✨ NAME ✨

al_set_target_bitmap — it's the Allegro 5 API function that tells everyone where to draw 💅

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

---

🦋 DESCRIPTION 🦋

so like. this function picks the bitmap that every single subsequent drawing operation in the calling thread is gonna draw to. that's the whole vibe. main character bitmap energy 👑

want to go back to drawing on a display? easy. just set the display's backbuffer as the target bitmap using al_get_backbuffer(3alleg5). and bc the Allegro devs are sweeties, there's a convenience shortcut too: al_set_target_backbuffer(3alleg5). slay 🫶

---

🎀 the matrix situation (not that kind)

every allegro bitmap keeps two transformation matrices associated with it, for drawing onto the bitmap:

• a view matrix
• and a projection matrix

when you call al_set_target_bitmap, these get made current for that bitmap, which lowkey affects global OpenGL and DirectX states depending on which driver you're running. iykyk.

---

🌈 video bitmaps & displays

every video bitmap is tied to a display. so when a video bitmap becomes the target bitmap, the display it belongs to is automatically made "current" for the calling thread (if it wasn't already current, obviously). once that's done, drawing other bitmaps that are tied to the same display can be hardware accelerated. fast. iconic. periodt ✨

⚠️ a single display cannot be current for multiple threads at the same time. no sharing, bestie, it's not that kind of party.

need to release a display so it's no longer current for the calling thread? just do:

al_set_target_bitmap(NULL);

and boom, released 💀

also note: setting a memory bitmap as the target bitmap will not change which display is current for the calling thread. no display drama there.

---

🍓 the preserve texture thing

on some platforms, Allegro automatically backs up the contents of video bitmaps bc they might occasionally get lost (there's a whole discussion in al_create_bitmap(3alleg5)'s documentation if you wanna go deep, bestie).

so if you're completely recreating the bitmap contents often — like, every single frame — you'll get much better performance by creating the target bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. do it. your framerate will thank you 🔥

---

👑 OpenGL note

framebuffer objects (FBOs) let OpenGL draw directly to a bitmap, which is very fast. when you're using an OpenGL display, an FBO gets created for use with the bitmap if all of these conditions are met:

• the GL_EXT_framebuffer_object OpenGL extension is available
• the bitmap is not a memory bitmap
• the bitmap is not currently locked

💀 the 5.0.0 lore

in Allegro 5.0.0 you had to be careful, bc an FBO would be kept around until the bitmap was destroyed or you explicitly called al_remove_opengl_fbo(3alleg5) on the bitmap — which just wasted resources, ngl. in newer versions, FBOs get freed automatically when the bitmap is no longer the target bitmap, unless you've called al_get_opengl_fbo(3alleg5) to retrieve the FBO id. character development fr fr 🌱

🙈 example where NO FBO gets created:

lock = al_lock_bitmap(bitmap);
al_set_target_bitmap(bitmap);
al_put_pixel(x, y, color);
al_unlock_bitmap(bitmap);

the above lets you use al_put_pixel(3alleg5) on a locked bitmap without creating an FBO. clever, right?

🔥 example where an FBO DOES get created:

al_set_target_bitmap(bitmap);
al_draw_line(x1, y1, x2, y2, color, 0);

an OpenGL command will be used to directly draw the line into the bitmap's associated texture. ate that 💅

---

⭐ SEE ALSO ⭐

• al_get_target_bitmap(3alleg5)
• al_set_target_backbuffer(3alleg5)

---

and that's the page, bestie 🧚💜 this was the al_set_target_bitmap(3alleg5) entry from the Allegro reference manual — go set that target and go slay. mwah 🎀✨