al_set_target_bitmap(3)

✨ NAME ✨

Okay bestie, this is the manual page for al_set_target_bitmap from the Allegro 5 API, straight out of the Allegro reference manual. It's giving "where do I draw?" energy and honestly it's iconic.

---

✨ SYNOPSIS ✨

#include <allegro5/allegro.h>

void al_set_target_bitmap(ALLEGRO_BITMAP *bitmap)

---

✨ DESCRIPTION ✨

So like, this function selects the bitmap that all your subsequent drawing operations in the calling thread will draw to. Think of it as picking your canvas — everything you draw after this call goes straight to that bitmap. 🎨✨

To return to drawing to a display, set the backbuffer of the display as the target bitmap, using al_get_backbuffer(3). As a convenience, you may also use al_set_target_backbuffer(3). Both are valid, no cap.

Each Allegro bitmap maintains two transformation matrices associated with it for drawing onto the bitmap. There's a view matrix and a projection matrix. When you call al_set_target_bitmap, these will be made current for the bitmap, affecting global OpenGL and DirectX states depending on the driver in use. So yeah, it's lowkey touching global state — main character energy. 👑

Each video bitmap is tied to a display. When a video bitmap is set as the target bitmap, the display that the bitmap belongs to is automatically made "current" for the calling thread (if it's not current already). Then drawing other bitmaps which are tied to the same display can be hardware accelerated. Slay for performance. 💅

⚠️ A single display cannot be current for multiple threads simultaneously. If you need to release a display so it's not current for the calling thread, call al_set_target_bitmap(NULL); — that's your escape hatch, bestie.

Setting a memory bitmap as the target bitmap will not change which display is current for the calling thread. Just so you know. 🧠

On some platforms, Allegro automatically backs up the contents of video bitmaps because they may be occasionally lost (see discussion in al_create_bitmap(3)'s documentation). If you're completely recreating the bitmap contents often (e.g. every frame) then you will get much better performance by creating the target bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. Trust me, your frame rate will thank you. 🔥

---

🌈 OpenGL note 🌈

Framebuffer objects (FBOs) allow OpenGL to directly draw to a bitmap, which is very fast. When using an OpenGL display, if all of the following conditions are met an FBO will be created for use with the bitmap:

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

In Allegro 5.0.0, you had to be careful as an FBO would be kept around until the bitmap is destroyed or you explicitly called al_remove_opengl_fbo(3) on the bitmap, wasting resources. In newer versions, FBOs will be freed automatically when the bitmap is no longer the target bitmap, unless you have called al_get_opengl_fbo(3) to retrieve the FBO id. So yeah, glow up from the old days. ✨

In the following example, no FBO will be created:

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

The above allows using al_put_pixel(3) on a locked bitmap without creating an FBO. Big brain move. 🧚

In this example an FBO is created however:

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. Chef's kiss. 👌

---

✨ SEE ALSO ✨

• al_get_target_bitmap(3)
• al_set_target_backbuffer(3)

---

That's the whole vibe, bestie! This page is from the Allegro reference manual — version al_set_target_bitmap(3) energy, dated whenever the manual was last updated. Stay slay, and remember: always know your target bitmap! 💖🎀🦋