ALLEGRO_PIXEL_FORMAT(3)

💖 ALLEGRO_PIXEL_FORMAT 💖

okay bestie, so this is a page from the Library Functions Manual for Allegro 5 (yes, that Allegro, the game programming library, we love her) — and imma walk you through every single pixel format because there are a lot and they all matter, no skipping 💅

---

✨ NAME ✨

ALLEGRO_PIXEL_FORMAT — the Allegro 5 API, specifically the pixel format situation 🎀

---

🌸 SYNOPSIS 🌸

#include <allegro5/allegro.h>

typedef enum ALLEGRO_PIXEL_FORMAT

---

🦋 DESCRIPTION 🦋

So. Pixel formats. Each one tells you the exact size and bit layout of a single pixel in memory — like the blueprints for how the bytes are arranged, and honestly it's giving interior design for memory 🏠✨

Components are listed from high bits to low bits. So for example, a fully opaque red pixel in ARGB_8888 format is:

0xFFFF0000

iconic, right? okay but here's the important part 👇

⚠️ Note, and this is a big one: the pixel format is independent of endianness. What that means for you is: in the above example you can always get the red component with this:

(pixel & 0x00ff0000) >> 16

But you cannot rely on this code:

*(pixel + 2)

It'll return the red component on little endian systems, but the green component on big endian systems. so like, don't do that, bestie 😭 it's a trap

---

Also pls note: Allegro's naming is different from OpenGL naming here, and this trips people up constantly. With OpenGL, a format like GL_RGBA8 merely defines the component order, and the exact layout including endianness treatment is specified separately. Usually GL_RGBA8 will correspond to ALLEGRO_PIXEL_ABGR_8888 though — on little endian systems — so care must be taken. note the reversal of RGBA <-> ABGR 🙈💀 like she really said "watch your step"

The one exception to all of that is ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE, which will always have the components as 4 bytes corresponding to red, green, blue and alpha, in this order, independent of the endianness. she's the reliable one 🫶

---

🎀 compressed formats, a whole vibe 🎀

Some of the pixel formats represent compressed bitmap formats, and ngl this is kind of the main character energy of the whole page:

• Compressed bitmaps take up less space in the GPU memory than bitmaps with regular (uncompressed) pixel formats ✨
• This smaller footprint means you can load more resources into GPU memory, and they will be drawn somewhat faster 🔥
• The compression is lossy, however, so it is not appropriate for all graphical styles — it tends to work best for images with smooth color gradations 🌈

It is possible to compress bitmaps at runtime by passing the appropriate bitmap format in al_set_new_bitmap_format and then creating, loading, cloning or converting a non-compressed bitmap. BUT — and I cannot stress this enough — this is not recommended, because the compression quality differs between different GPU drivers 😭 It is recommended to compress these bitmaps ahead of time using external tools and then load them compressed. do it the right way, i'm begging 💀

---

🧚 how compressed bitmaps are laid out 🧚

Unlike regular pixel formats, compressed pixel formats are not laid out in memory one pixel row at a time. Instead, the bitmap is subdivided into rectangular blocks of pixels that are then laid out in block rows.

Which means: regular locking functions cannot use compressed pixel formats as the destination format 🚫 Instead, you can use the blocked versions of the bitmap locking functions, which do support these formats. iykyk 💅

Also: it is not recommended to use compressed bitmaps as target bitmaps, as that operation cannot be hardware accelerated. And due to proprietary algorithms used, it is typically impossible to create compressed memory bitmaps. so like... don't even try, she said no 😤

---

👑 the formats themselves, all 31 of them 👑

• ALLEGRO_PIXEL_FORMAT_ANY — Let the driver choose a format. This is the default format at program start. (the "you pick, i trust you" option 🫶)
• ALLEGRO_PIXEL_FORMAT_ANY_NO_ALPHA — Let the driver choose a format without alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_WITH_ALPHA — Let the driver choose a format with alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_15_NO_ALPHA — Let the driver choose a 15 bit format without alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_16_NO_ALPHA — Let the driver choose a 16 bit format without alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_16_WITH_ALPHA — Let the driver choose a 16 bit format with alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_24_NO_ALPHA — Let the driver choose a 24 bit format without alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_32_NO_ALPHA — Let the driver choose a 32 bit format without alpha.
• ALLEGRO_PIXEL_FORMAT_ANY_32_WITH_ALPHA — Let the driver choose a 32 bit format with alpha.
• ALLEGRO_PIXEL_FORMAT_ARGB_8888 — 32 bit
• ALLEGRO_PIXEL_FORMAT_RGBA_8888 — 32 bit
• ALLEGRO_PIXEL_FORMAT_ARGB_4444 — 16 bit
• ALLEGRO_PIXEL_FORMAT_RGB_888 — 24 bit
• ALLEGRO_PIXEL_FORMAT_RGB_565 — 16 bit
• ALLEGRO_PIXEL_FORMAT_RGB_555 — 15 bit
• ALLEGRO_PIXEL_FORMAT_RGBA_5551 — 16 bit
• ALLEGRO_PIXEL_FORMAT_ARGB_1555 — 16 bit
• ALLEGRO_PIXEL_FORMAT_ABGR_8888 — 32 bit
• ALLEGRO_PIXEL_FORMAT_XBGR_8888 — 32 bit
• ALLEGRO_PIXEL_FORMAT_BGR_888 — 24 bit
• ALLEGRO_PIXEL_FORMAT_BGR_565 — 16 bit
• ALLEGRO_PIXEL_FORMAT_BGR_555 — 15 bit
• ALLEGRO_PIXEL_FORMAT_RGBX_8888 — 32 bit
• ALLEGRO_PIXEL_FORMAT_XRGB_8888 — 32 bit
• ALLEGRO_PIXEL_FORMAT_ABGR_F32 — 128 bit
• ALLEGRO_PIXEL_FORMAT_ABGR_8888_LE — Like the version without _LE, but the component order is guaranteed to be red, green, blue, alpha. This only makes a difference on big endian systems; on little endian it is just an alias. (the humble queen 👑)
• ALLEGRO_PIXEL_FORMAT_RGBA_4444 — 16bit
• ALLEGRO_PIXEL_FORMAT_SINGLE_CHANNEL_8 — A single 8-bit channel. A pixel value maps onto the red channel when displayed, but it is undefined how it maps onto green, blue and alpha channels 🙈 When drawing to bitmaps of this format, only the red channel is taken into account. Allegro may have to use fallback methods to render to bitmaps of this format. This pixel format is mainly intended for storing the color indices of an indexed (paletted) image, usually in conjunction with a pixel shader that maps indices to RGBA values. Since 5.1.2.
• ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT1 — Compressed using the DXT1 compression algorithm. Each 4x4 pixel block is encoded in 64 bytes, resulting in 6-8x compression ratio. Only a single bit of alpha per pixel is supported. Since 5.1.9.
• ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT3 — Compressed using the DXT3 compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression ratio. This format supports sharp alpha transitions. Since 5.1.9.
• ALLEGRO_PIXEL_FORMAT_COMPRESSED_RGBA_DXT5 — Compressed using the DXT5 compression algorithm. Each 4x4 pixel block is encoded in 128 bytes, resulting in 4x compression ratio. This format supports smooth alpha transitions. Since 5.1.9.

---

🌟 SEE ALSO 🌟

• al_set_new_bitmap_format(3)
• al_get_bitmap_format(3)

go read those next bestie, they're the other half of this whole story 💖

---

mwah 💋 that's the whole page — this came straight out of the Allegro reference manual and the page itself is ALLEGRO_PIXEL_FORMAT(3), so now you know exactly where to find her again 🎀✨