set_color_conversion(3)

📦 version 4.4.3.1, in fedora 43, fedora 44

✨ NAME ✨

set_color_conversion — the function that tells Allegro how it's allowed to convert your images while they're being loaded. 🎀

(oh also hiii this is a page from the Allegro manual, bestie, come sit with me 💖)

🌸 SYNOPSIS 🌸

#include <allegro.h>

void set_color_conversion(int mode);

💅 DESCRIPTION 💅

Okay so picture this: Allegro is reading a bitmap off your disk, or out of a datafile, and the image on disk is in some color depth, and your current video mode is in some other color depth. This function is the one that decides whether Allegro is allowed to just handle that glow-up for you, or whether it leaves the data exactly as it found it. 👑

mode is a bitmask — so it's not one setting, it's a whole little bouquet of "yes you may do this" flags. If the appropriate bit is set, the data gets converted into the current pixel format (the one you picked by calling set_color_depth()), and if it's not set, the data just stays in the same format as the disk file. Which means… yeah, you're converting it manually before it can be displayed, bestie. Your problem now. 😭

The default mode is total conversion, so all images get loaded in the appropriate format for the current video mode. Periodt.

Valid bit flags, and yes there are a LOT of them, she contains multitudes:

  • COLORCONV_NONE — disable all format conversions. literally none of them. nope. 🙈
  • COLORCONV_8_TO_15 — expand 8-bit to 15-bit
  • COLORCONV_8_TO_16 — expand 8-bit to 16-bit
  • COLORCONV_8_TO_24 — expand 8-bit to 24-bit
  • COLORCONV_8_TO_32 — expand 8-bit to 32-bit
  • COLORCONV_15_TO_8 — reduce 15-bit to 8-bit
  • COLORCONV_15_TO_16 — expand 15-bit to 16-bit
  • COLORCONV_15_TO_24 — expand 15-bit to 24-bit
  • COLORCONV_15_TO_32 — expand 15-bit to 32-bit
  • COLORCONV_16_TO_8 — reduce 16-bit to 8-bit
  • COLORCONV_16_TO_15 — reduce 16-bit to 15-bit
  • COLORCONV_16_TO_24 — expand 16-bit to 24-bit
  • COLORCONV_16_TO_32 — expand 16-bit to 32-bit
  • COLORCONV_24_TO_8 — reduce 24-bit to 8-bit
  • COLORCONV_24_TO_15 — reduce 24-bit to 15-bit
  • COLORCONV_24_TO_16 — reduce 24-bit to 16-bit
  • COLORCONV_24_TO_32 — expand 24-bit to 32-bit
  • COLORCONV_32_TO_8 — reduce 32-bit RGB to 8-bit
  • COLORCONV_32_TO_15 — reduce 32-bit RGB to 15-bit
  • COLORCONV_32_TO_16 — reduce 32-bit RGB to 16-bit
  • COLORCONV_32_TO_24 — reduce 32-bit RGB to 24-bit
  • COLORCONV_32A_TO_8 — reduce 32-bit RGBA to 8-bit
  • COLORCONV_32A_TO_15 — reduce 32-bit RGBA to 15-bit
  • COLORCONV_32A_TO_16 — reduce 32-bit RGBA to 16-bit
  • COLORCONV_32A_TO_24 — reduce 32-bit RGBA to 24-bit
  • COLORCONV_DITHER_PAL — dither when reducing to 8-bit
  • COLORCONV_DITHER_HI — dither when reducing to hicolor
  • COLORCONV_KEEP_TRANS — keep original transparency

🦋 the convenience macros 🦋

Because typing all of that out is so much, Allegro ships some macros that bundle up the common combos for you. Slay:

  • COLORCONV_EXPAND_256 — expand 256-color to hi/truecolor
  • COLORCONV_REDUCE_TO_256 — reduce hi/truecolor to 256-color
  • COLORCONV_EXPAND_15_TO_16 — expand 15-bit hicolor to 16-bit
  • COLORCONV_REDUCE_16_TO_15 — reduce 16-bit hicolor to 15-bit
  • COLORCONV_EXPAND_HI_TO_TRUE — expand 15/16-bit to 24/32-bit
  • COLORCONV_REDUCE_TRUE_TO_HI — reduce 24/32-bit to 15/16-bit
  • COLORCONV_24_EQUALS_32 — convert between 24- and 32-bit
  • COLORCONV_TOTAL — everything to current format
  • COLORCONV_PARTIAL — convert 15 <-> 16-bit and 24 <-> 32-bit
  • COLORCONV_MOST — all but hi/truecolor <-> 256
  • COLORCONV_DITHER — dither during all color reductions
  • COLORCONV_KEEP_ALPHA — convert everything to current format unless it would lose alpha information

🔥 the dithering tea 🔥

So if you turn on the COLORCONV_DITHER flag, dithering happens whenever truecolor graphics get converted into a hicolor or paletted format. And bestie, that's not just at load time — it also includes conversions done by the blit() function, plus any automatic conversions that happen while reading graphics from disk. ✨

It can produce much better looking results, but it is obviously slower than a direct conversion. You are paying for that glow-up in frames, and that's just the deal. 💀

🎀 the transparency situation 🎀

If you're planning to use your converted bitmaps with stuff like masked_blit() or draw_sprite(), you want to specify the COLORCONV_KEEP_TRANS flag. Here's why it's iconic: it makes sure the masked areas in the bitmap stay exactly the same before and after the conversion. How? By mapping transparent colors to each other, and by adjusting colors that would otherwise get converted into the transparent color. 🫶

Heads up: it affects every blit() operation between distinct pixel formats, and every automatic conversion. So it's not a sometimes-thing, it's an always-thing. 🧚

👑 SEE ALSO 👑

set_color_depth(3), load_bitmap(3), load_datafile(3), fixup_datafile(3), makecol15_dither(3), get_color_conversion(3), exalpha(3), exblend(3), exdata(3), exexedat(3), exlights(3), exrotscl(3), exxfade(3)

okay that's the whole page, bestie, you ate that 💖 this was brought to you by the Allegro manual, version 4.4.3 — and yes that's the version, she's vintage, she's timeless, she's lowkey iconic for it. now go convert something. periodt. 💅🌈⭐

📦 where this page comes from