Allegro Manual: Converting between color formats

# Converting between color formats

- bestfit_color — Finds a palette color fitting the requested RGB values.
- create_rgb_table — Generates an RGB mapping table with lookup data for a palette.
- hsv_to_rgb — Converts color values between the HSV and RGB color spaces.
- rgb_map — Look up table to speed up reducing RGB values to palette colors.
- rgb_to_hsv — Converts color values between the HSV and RGB color spaces.

In general, Allegro is designed to be used in only one color depth at a time, so you will call set_color_depth() once and then store all your bitmaps in the same format. If you want to mix several different pixel formats, you can use create_bitmap_ex() in place of create_bitmap(), and call bitmap_color_depth() to query the format of a specific image. Most of the graphics routines require all their input parameters to be in the same format (eg. you cannot stretch a 15-bit source bitmap onto a 24-bit destination), but there are some exceptions:

- blit() and the rotation routines can copy between bitmaps of any format, converting the data as required.
- draw_sprite() can draw 256-color source images onto destinations of any format.
- draw_character_ex() _always_ uses a 256-color source bitmap, whatever the format of the destination.
- The draw_trans_sprite() and draw_trans_rle_sprite() functions are able to draw 32-bit RGBA images onto any hicolor or truecolor destination, as long as you call set_alpha_blender() first.
- The draw_trans_sprite() function is able to draw an 8-bit alpha channel image over the top of an existing 32-bit image, as long as you call set_write_alpha_blender() first.

Expanding a 256-color source onto a truecolor destination is fairly fast (obviously you must set the correct palette before doing this conversion!). Converting between different truecolor formats is slightly slower, and reducing truecolor images to a 256-color destination is very slow (it can be sped up significantly if you set up the global rgb_map table before doing the conversion).

int bestfit_color(const PALETTE pal, int r, int g, int b);
Searches the specified palette for the closest match to the requested color, which are specified in the VGA hardware 0-63 format. Normally you should call makecol8() instead, but this lower level function may be useful if you need to use a palette other than the currently selected one, or specifically don't want to use the rgb_map lookup table.

Return value: Returns the index of the palette for the closest match to the requested color.

> See also: makecol8.

extern RGB_MAP *rgb_map;
To speed up reducing RGB values to 8-bit paletted colors, Allegro uses a 32k lookup table (5 bits for each color component). You must set up this table before using the gouraud shading routines, and if present the table will also vastly accelerate the makecol8() and some create_*_table() functions. RGB tables can be precalculated with the rgbmap utility, or generated at runtime with create_rgb_table().

> See also: create_rgb_table, makecol8, create_trans_table, create_light_table, create_color_table.

> Examples using this: ex3d, excolmap, exrgbhsv, exshade, extrans.

void create_rgb_table(RGB_MAP *table, const PALETTE pal, void (*callback)(int pos));
Fills the specified RGB mapping table with lookup data for the specified palette. If the callback function is not NULL, it will be called 256 times during the calculation, allowing you to display a progress indicator. Example:

>           RGB_MAP rgb_table;

>           create_rgb_table(&rgb_table, palette, NULL);
>           rgb_map = &rgb_table;

> See also: rgb_map.

> Examples using this: ex3d, excolmap, exrgbhsv, exshade, extrans.

void hsv_to_rgb(float h, float s, float v, int *r, int *g, int *b);
void rgb_to_hsv(int r, int g, int b, float *h, float *s, float *v);
Convert color values between the HSV and RGB color spaces. The RGB values range from 0 to 255, hue is from 0 to 360, and saturation and value are from 0 to 1. Example:

>           int r, g, b;
>           float hue, saturation, value;
>           ...
>           /* Convert a reddish color to HSV format. */
>           rgb_to_hsv(255, 0, 128, &hue, &saturation, &value);

>           /* Now put our tin foil hat, and verify that. */
>           hsv_to_rgb(hue, saturation, value, &r, &g, &b);
>           ASSERT(r == 255);
>           ASSERT(g == 0);
>           ASSERT(b == 128);

> Examples using this: exlights, exrgbhsv.

Back to contents