1ColorUtils
2##########
3
4These functions are used for general purpose color-related tasks.
5
6Global Functions
7================
8
9void SetRGBColor32(rgb_color \*col, uint8 r, uint8 g, uint8 b, uint8 a=255)
10---------------------------------------------------------------------------
11
12Simply assigns the passed parameters to the internal members of the
13passed color
14
15void SetRGBAColor32(rgb_color \*col, uint16 color16)
16----------------------------------------------------
17
18Maps a 16-bit color to a 32-bit one.
19
20gggbbbbb arrrrrgg
21
221. Extract component values using the following calculations:
23
24   .. code-block:: cpp
25
26      red16 = (uint8[1] & 124) >> 2;
27      green16 = ((uint8[0] & 224) >> 5) | ((uint8[1] & 3) << 3);
28      blue16 = uint8[0] & 31;
29
302. Use cross-multiplication to map each 16-bit color component from 0-31
31   space to 0-255 space, i.e. red32 = (red16 / 31) \* 255
323. Assign mapped values to the rgb_color passed to the function
33
34void SetRGBColor16(uint16 \*col, uint8 r, uint8 g, uint8 b)
35-----------------------------------------------------------
36
37Used for easy assignment of opaque (B_RGB16) 16-bit colors.
38
391. Clip parameters via a bitwise AND with 31 (var &=31)
402. Create a uint8 * to the passed color
413. Assign as follows and return:
42
43   .. code-block:: cpp
44
45      uint8[0] = ( (g & 7) << 5) | (b & 31);
46      uint8[1] = ( (r & 31) << 3) | ( (g & 56) >> 3);
47
48void SetRGBAColor15(uint16 \*col, uint8 r, uint8 g, uint8 b, bool opaque=true)
49------------------------------------------------------------------------------
50
51Used for easy assignment of alpha-aware (B_RGBA16) 16-bit colors.
52
531. Clip parameters via a bitwise AND with 31 (var &=31)
542. Create a uint8 * to the passed color
553. Assign as follows and return:
56
57   .. code-block:: cpp
58
59      uint8[0] = ( (g & 7) << 5) | (b & 31);
60      uint8[1] = ( (r & 31) << 2) | ( (g & 24) >> 3) | (a) ? 128 : 0;
61
62uint8 FindClosestColor(rgb_color \*palette,rgb_color col)
63---------------------------------------------------------
64
65Finds the color which most closely resembles the given one in the
66given palette.
67
681. Set the saved delta value to 765 (maximum difference)
692. Loop through all the colors in the palette. For each color,
70
71   a. calculate the delta value for each color component and add them
72      together
73   b. compare the new combined delta with the saved one
74   c. if the delta is 0, immediately return the current index
75   d. if the new one is smaller, save it and also the palette index
76
77uint16 FindClosestColor16(rgb_color col)
78----------------------------------------
79
80Returns a 16-bit approximation of the given 32-bit color. Alpha values
81are ignored.
82
831. Create an opaque, 16-bit approximation of col using the following
84   calculations:
85
86   .. code-block:: cpp
87
88      r16 = (31 * col.red) / 255;
89      g16 = (31 * col.green) / 255;
90      b16 = (31 * col.blue) / 255;
91
922. Assign it to a uint16 using the same code as in SetRGBColor16() and
93   return it.
94
95uint16 FindClosestColor15(rgb_color col)
96----------------------------------------
97
98This functions almost exactly like the 16-bit version, but this also
99takes into account the alpha transparency bit and works in the color
100space B_RGBA15. Follow the same algorithm as FindClosestColor16(), but
101assign the return value using SetRGBColor15.
102
103rgb_color MakeBlendColor(rgb_color col, rgb_color col2, float position)
104-----------------------------------------------------------------------
105
106MakeBlendColor calculates a color that is somewhere between start
107color col and end color col2, based on position, where 0<= position <=
1081. If position is out of these bounds, a color of {0,0,0,0} is
109returned. If position is 0, the start color is returned. If position
110is 1, col2 is returned. Otherwise, the color is calculated thus:
111
1121. calculate delta values for each channel, i.e. int16 delta_r=col.red-col2.red
1132. Based on these delta values, calculate the blend values for each
114   channel, i.e. blend_color.red=uint8(col1.red - (delta_r \* position) )
115