Palette routines

All the Allegro drawing functions use integer parameters to represent colors. In truecolor resolutions these numbers encode the color directly as a collection of red, green, and blue bits, but in a regular 256-color mode the values are treated as indexes into the current palette, which is a table listing the red, green and blue intensities for each of the 256 possible colors.

Palette entries are stored in an RGB structure, which contains red, green and blue intensities in the VGA hardware format, ranging from 0-63, and is defined as: 

   typedef struct RGB
   {
      unsigned char r, g, b;
   } RGB;
It contains an additional field for the purpose of padding but you should not usually care about it. For example: 
   RGB black = { 0,  0,  0  };
   RGB white = { 63, 63, 63 };
   RGB green = { 0,  63, 0  };
   RGB grey  = { 32, 32, 32 };
The type PALETTE is defined to be an array of PAL_SIZE RGB structures, where PAL_SIZE is a preprocessor constant equal to 256.

You may notice that a lot of the code in Allegro spells 'palette' as 'pallete'. This is because the headers from my old Mark Williams compiler on the Atari spelt it with two l's, so that is what I'm used to. Allegro will happily accept either spelling, due to some #defines in allegro/alcompat.h (which can be turned off by defining the ALLEGRO_NO_COMPATIBILITY symbol before including Allegro headers).


void set_color(int index, const RGB *p);

Sets the specified palette entry to the specified RGB triplet. Unlike the other palette functions this doesn't do any retrace synchronisation, so you should call vsync() before it to prevent snow problems. Example: 
      RGB rgb;
      ...
      vsync();
      set_color(192, &rgb);
See also: set_palette, get_color, _set_color.
Examples using this: ex12bit, exrgbhsv, exscroll.
void _set_color(int index, const RGB *p);

This is an inline version of set_color(), intended for use in the vertical retrace simulator callback function (retrace_proc, which is now deprecated).

If you really must use _set_color from retrace_proc, note that it should only be used under DOS, in VGA mode 13h and mode-X. Some SVGA chipsets aren't VGA compatible (set_color() and set_palette() will use VESA calls on these cards, but _set_color() doesn't know about that).

See also: set_color, set_gfx_mode.
Examples using this: ex3buf.
void set_palette(const PALETTE p);

Sets the entire palette of 256 colors. You should provide an array of 256 RGB structures. Unlike set_color(), there is no need to call vsync() before this function. Example: 
      BITMAP *bmp;
      PALETTE palette;
      ...
      bmp = load_bitmap(filename, palette);
      if (!bmp)
         abort_on_error("Couldn't load bitmap!");
      set_palette(palette);
See also: set_gfx_mode, set_palette_range, set_color, get_palette, select_palette, palette_color.
Examples using this: Available Allegro examples.
void set_palette_range(const PALETTE p, int from, int to, int vsync);

Sets the palette entries between from and to (inclusive: pass 0 and 255 to set the entire palette). If vsync is set it waits for the vertical retrace, otherwise it sets the colors immediately. Example: 
      PALETTE palette;
      ...
      /* Modify the first 16 entries. */
      change_first_16_colors(palette);
      /* Now update them waiting for vsync. */
      set_palette_range(palette, 0, 15, 1);
See also: set_palette, get_palette_range.
Examples using this: exzbuf.
void get_color(int index, RGB *p);

Retrieves the specified palette entry. Example: 
      RGB color;
      ...
      get_color(11, &color);
See also: get_palette, set_color.
void get_palette(PALETTE p);

Retrieves the entire palette of 256 colors. You should provide an array of 256 RGB structures to store it in. Example: 
      PALETTE pal;
      ...
      get_palette(pal);
See also: get_palette_range, get_color, set_palette.
void get_palette_range(PALETTE p, int from, int to);

Retrieves the palette entries between from and to (inclusive: pass 0 and 255 to get the entire palette).
See also: get_palette, set_palette_range.
void fade_interpolate(const PALETTE source, const PALETTE dest, PALETTE output, int pos, int from, int to);

Calculates a temporary palette part way between source and dest, returning it in the output parameter. The position between the two extremes is specified by the pos value: 0 returns an exact copy of source, 64 returns dest, 32 returns a palette half way between the two, etc. This routine only affects colors between from and to (inclusive: pass 0 and 255 to interpolate the entire palette).
See also: fade_in, fade_out, fade_from.
void fade_from_range(const PALETTE source, const PALETTE dest, int speed, int from, int to);

Gradually fades a part of the palette from the source palette to the dest palette. The speed is from 1 (the slowest) up to 64 (instantaneous). This routine only affects colors between from and to (inclusive: pass 0 and 255 to fade the entire palette).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also: fade_from.
void fade_in_range(const PALETTE p, int speed, int from, int to);

Gradually fades a part of the palette from a black screen to the specified palette. The speed is from 1 (the slowest) up to 64 (instantaneous). This routine only affects colors between from and to (inclusive: pass 0 and 255 to fade the entire palette).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also: fade_in.
void fade_out_range(int speed, int from, int to);

Gradually fades a part of the palette from the current palette to a black screen. The speed is from 1 (the slowest) up to 64 (instantaneous). This routine only affects colors between from and to (inclusive: pass 0 and 255 to fade the entire palette).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also: fade_out.
void fade_from(const PALETTE source, const PALETTE dest, int speed);

Fades gradually from the source palette to the dest palette. The speed is from 1 (the slowest) up to 64 (instantaneous).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also: fade_in, fade_out, fade_interpolate, fade_from_range.
void fade_in(const PALETTE p, int speed);

Fades gradually from a black screen to the specified palette. The speed is from 1 (the slowest) up to 64 (instantaneous).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also: fade_out, fade_from, fade_interpolate, fade_in_range.
void fade_out(int speed);

Fades gradually from the current palette to a black screen. The speed is from 1 (the slowest) up to 64 (instantaneous).

Note that this function will block your game while the fade is in effect, and it won't work right visually if you are not in an 8 bit color depth resolution.

See also: fade_in, fade_from, fade_interpolate, fade_in_range.
Examples using this: ex12bit.
void select_palette(const PALETTE p);

Ugly hack for use in various dodgy situations where you need to convert between paletted and truecolor image formats. Sets the internal palette table in the same way as the set_palette() function, so the conversion will use the specified palette, but without affecting the display hardware in any way. The previous palette settings are stored in an internal buffer, and can be restored by calling unselect_palette(). If you call select_palette() again, however, the internal buffer will be overwritten.
See also: set_palette, unselect_palette.
Examples using this: exlights.
void unselect_palette();

Restores the palette tables that were in use before the last call to select_palette().
See also: select_palette.
void generate_332_palette(PALETTE pal);

Constructs a fake truecolor palette, using three bits for red and green and two for the blue. The load_bitmap() function fills the palette parameter with this if the file does not contain a palette itself (ie. you are reading a truecolor bitmap).
See also: generate_optimized_palette, set_color_depth.
Examples using this: excolmap, exrgbhsv, extruec, exupdate.
int generate_optimized_palette(BITMAP *bmp, PALETTE pal, const char rsvd[PAL_SIZE]);

Generates a 256-color palette suitable for making a reduced color version of the specified truecolor image. The rsvd parameter points to a table indicating which colors it is allowed to modify: zero for free colors which may be set to whatever the optimiser likes, negative values for reserved colors which cannot be used, and positive values for fixed palette entries that must not be changed, but can be used in the optimisation.

Return value: Returns the number of different colors recognised in the provided bitmap, zero if the bitmap is not a truecolor image or there wasn't enough memory to perform the operation, and negative if there was any internal error in the color reduction code.

See also: generate_332_palette, set_color_depth.
extern PALETTE default_palette;

The default IBM BIOS palette. This will be automatically selected whenever you set a new graphics mode. The palette contains 16 basic colors plus many gradients between them. If you want to see the values, you can write a small Allegro program which saves a screenshot with this palette, or open the grabber tool provided with Allegro and create a new palette object, which will use this palette by default.
See also: black_palette, desktop_palette.
Examples using this: exjoy.
extern PALETTE black_palette;

A palette containing solid black colors, used by the fade routines.
See also: default_palette, desktop_palette.
Examples using this: expal.
extern PALETTE desktop_palette;

The palette used by the Atari ST low resolution desktop. I'm not quite sure why this is still here, except that the grabber and test programs use it. It is probably the only Atari legacy code left in Allegro, and it would be a shame to remove it :-)

The contents of this palette are 16 colors repeated 16 times. Color entry zero is equal to color entry 16, which is equal to color entry 24, etc. 

       Index      Color       RGB values
         0     White          63  63  63
         1     Red            63   0   0
         2     Green           0  63   0
         3     Yellow         63  63   0
         4     Blue            0   0  63
         5     Pink           63   0  63
         6     Cyan            0  63  63
         7     Grey           16  16  16
         8     Light grey     31  31  31
         9     Light red      63  31  31
        10     Light green    31  63  31
        11     Light yellow   63  63  31
        12     Light blue     31  31  63
        13     Light pink     63  31  63
        14     Light cyan     31  63  63
        15     Black           0   0   0
See also: default_palette, black_palette.
Examples using this: Available Allegro examples.
Back to contents