Google

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;
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 256 RGB structures.

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.

void vsync();
Waits for a vertical retrace to begin. The retrace happens when the electron beam in your monitor has reached the bottom of the screen and is moving back to the top ready for another scan. During this short period the graphics card isn't sending any data to the monitor, so you can do things to it that aren't possible at other times, such as altering the palette without causing flickering (snow). Allegro will automatically wait for a retrace before altering the palette or doing any hardware scrolling, though, so you don't normally need to bother with this function.

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.

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. It should only be used in VGA mode 13h and mode-X, because some of the more recent 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).

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.

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.

void get_color(int index, RGB *p);
Retrieves the specified palette entry.

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.

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).

void fade_interpolate(const PALETTE source, const PALETTE dest, PALETTE output, int pos, int from, 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).

void fade_from_range(const PALETTE source, const PALETTE dest, int speed, int from, 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).

void fade_in_range(const PALETTE p, int speed, int from, 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).

void fade_out_range(int speed, int from, 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).

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).

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).

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).

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().

void unselect_palette();
Restores the palette tables that were in use before the last call to 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 returns this if the file does not contain a palette itself (ie. you are reading a truecolor bitmap).

int generate_optimized_palette(BITMAP *bmp, PALETTE pal, const char rsvd[256]);
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.

extern PALETTE default_palette;
The default IBM BIOS palette. This will be automatically selected whenever you set a new graphics mode.

extern PALETTE black_palette;
A palette containing solid black colors, used by the fade routines.

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 :-)