Explicit values for red, green, and blue (RGB)COLORREF
A COLORREF color value is a long integer that specifies a color. GDI functions that require a color (such as CreatePen and FloodFill) accept a COLORREF value as a parameter. Depending on how an application uses the COLORREF value, the value has three distinct forms. It may specify any of the following:
Explicit values for red, green, and blue (RGB)
An index into a logical color palette
A palette-relative RGB value
When specifying an explicit RGB value, the COLORREF value has the following hexadecimal form:
0x00bbggrr
The low-order byte contains a value for the relative intensity of red; the second byte contains a value for green, and the third byte contains a value for blue. The high-order byte must be zero. The maximum value for a single byte is FF (hexadecimal). The following list illustrates the hexadecimal values that produce the indicated colors:
| Value | Color |
| 0x000000FF | Pure red |
| 0x0000FF00 | Pure green |
| 0x00FF0000 | Pure blue |
| 0x00000000 | Black |
| 0x00FFFFFF | White |
| 0x00808080 | Medium gray |
The RGB macro accepts values for red, green, and blue, and returns an explicit RGB COLORREF value.
Palette Index
When specifying an index into a logical color palette, the COLORREF value has the following hexadecimal form:
0x0100iiii
The two low-order bytes consist of a 16-bit integer specifying an index into a logical palette. The third byte is not used and must be zero. The fourth (high-order) byte must be set to 1.
For example, the hexadecimal value 0x01000000 specifies the color in the palette entry of index 0; 0x0100000C specifies the color in the entry of index 12, and so on.
The PALETTEINDEX macro accepts an integer representing an index into a logical palette and returns a palette-index COLORREF value.
Palette-Relative RGB
When specifying a palette-relative RGB value, the COLORREF value has the following hexadecimal form:
0x02bbggrr
As with an explicit RGB, the three low-order bytes contain values for red, green, and blue; the high-order byte must be set to 2.
For output devices that support logical palettes, Windows matches a palette-relative RGB value to the nearest color in the logical palette of the device context, as though the application had specified an index to that palette entry. If an output device does not support a system palette, then Windows uses the palette-relative RGB as though it were an explicit RGB COLORREF value.
The PALETTERGB macro accepts values for red, green, and blue, and returns a palette-relative RGB COLORREF value.
Before passing a palette-index or palette-relative RGB COLORREF value to a function that also requires a device-context parameter, an application that uses its own palette must select its palette into the device context (by calling the SelectPalette function) and realize the palette (by calling RealizePalette). This ensures that the function will use the correct palette-entry color. For functions that create an object (such as CreatePen), the application must select and realize the palette before selecting the object for the device context.
CreatePen, RealizePalette, RGB, SelectPalette