al_create_bitmap(3alleg5)

✨ NAME ✨

al_create_bitmap — the Allegro 5 API glow-up that literally ✨makes✨ you a brand new bitmap 🎀

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

ALLEGRO_BITMAP *al_create_bitmap(int w, int h)

---

💖 DESCRIPTION 💖

okay bestie, so al_create_bitmap spins you up a fresh new bitmap, and it uses whatever bitmap format and flags are currently set for this thread. That's the whole vibe. 🦋

ngl though, blitting between bitmaps that have different formats, or blitting between memory bitmaps and display bitmaps? may be slow. so like, be mindful. 💀

Unless you set the ALLEGRO_MEMORY_BITMAP flag, your bitmap gets created for the current display. And if you then blit it to a different display, that may be slow too. it's giving cross-display travel fatigue fr fr 😭

---

🎀 the dimension tea (display bitmaps only) 🎀

If a display bitmap is what you're creating, there may be limits on the dimensions you're allowed to use:

• For example, a DirectX or OpenGL backend usually has a maximum allowed texture size. so if bitmap creation fails for very large dimensions, you might wanna re-try with a smaller bitmap. 💅
• Some platforms also dictate a minimum texture size, and that's relevant if you plan to use this bitmap with the primitives addon.
  • If you try to create a bitmap smaller than that minimum, this call will not fail — but the returned bitmap will be a section of a larger bitmap with the minimum size. sneaky but iconic.
  • The minimum size that works on all platforms is 32 by 32. periodt. ⭐
  • There's an experimental switch to turn this padding off by editing the system configuration (see the min_bitmap_size key in al_get_system_config(3alleg5)).

---

🌈 the powers-of-two situation 🌈

Some platforms do not directly support display bitmaps whose dimensions are not powers of two. Allegro handles this by:

1. creating a larger bitmap that has dimensions that are powers of two, and then
2. returning a section of that bitmap with the dimensions you requested. 🫶

This can be relevant if you plan to use this bitmap with the primitives addon — but it shouldn't be an issue otherwise. so like, chill. 😌

---

🦋 no display? no problem 🦋

If you create a bitmap without ALLEGRO_MEMORY_BITMAP set, but there's no current display, a temporary memory bitmap will be created instead. You can later convert all such bitmaps to video bitmap and assign them to a display by calling al_convert_memory_bitmaps(3alleg5). ✨

---

💀 the lost-focus drama 💀

On some platforms the contents of video bitmaps may be lost when your application loses focus. Allegro has an internal mechanism to restore the contents of these video bitmaps, but:

it is not foolproof (sometimes bitmap contents can get lost permanently) and it has performance implications. 🙈

If you're using a bitmap as an intermediate buffer, this mechanism may be wasteful. In that case, if you do not want Allegro managing the bitmap contents for you, you can disable this mechanism by creating the bitmap with the ALLEGRO_NO_PRESERVE_TEXTURE flag. 🔥

Here's the event choreography, bestie:

• The bitmap contents are lost when you get the ALLEGRO_EVENT_DISPLAY_LOST and ALLEGRO_EVENT_DISPLAY_HALT_DRAWING events.
• They should be restored when you get the ALLEGRO_EVENT_DISPLAY_FOUND event and when you call al_acknowledge_drawing_resume(3alleg5) (after the ALLEGRO_EVENT_DISPLAY_RESUME_DRAWING event).

You can use those events to implement your own bitmap content restoration mechanism if Allegro's doesn't work well enough for you — for example, you can reload them all from disk. main character energy, honestly 👑

---

⭐ the big note ⭐

Note: the contents of a newly created bitmap are undefined — you need to clear the bitmap or make sure all pixels get overwritten before drawing it. no cap.

And when you're done using the bitmap, you must call al_destroy_bitmap(3alleg5) on it to free any resources allocated for it. clean up after yourself, queen 💅

---

👑 SEE ALSO 👑

• al_set_new_bitmap_format(3alleg5)
• al_set_new_bitmap_flags(3alleg5)
• al_clone_bitmap(3alleg5)
• al_create_sub_bitmap(3alleg5)
• al_convert_memory_bitmaps(3alleg5)
• al_destroy_bitmap(3alleg5)

---

and that's the whole page, bestie 🫶 this came straight out of the Allegro reference manual — the Allegro 5 API edition — so go forth and allocate responsibly. mwah 💖✨