GDI Support for Palettes

GDI can do most of the work with regard to palette management. When GDI calls DrvEnablePDEV, the driver returns its default palette to GDI as part of the DEVINFO structure. The driver should create this palette with EngCreatePalette.

A palette effectively maps 32-bit color indexes into 24-bit RGB color values, which is the way GDI uses palettes. A driver specifies its palette so GDI can determine how different color indexes are to appear on the device.

The driver need not deal with most palette operations and calculations as long as it uses the XLATEOBJ provided by GDI.

If the device supports a modifiable palette, it should implement DrvSetPalette. GDI calls DrvSetPalette when an application changes the palette for a device and passes the resulting new palette to the driver. The driver should set its internal hardware palette to match the new palette as closely as possible.

A palette can be defined for GDI in either of the two different formats listed in the following table.

Palette Format

Description

Indexed

A color index is an index into an array of RGB values. The array can be small, containing, for example, 16 color indexes; or large, containing, for example, 4096 color indexes or more.

Bit Fields

Bit fields in the color index specify colors in terms of the amounts of R, G, and B in each color. For example, 5 bits could be used for each, providing a value between 0 and 31 for each color. The 5-bit value would be scaled up to cover a range of 0 to 255 for each component when converting to RGB. (The usual RGB representation itself is defined by bit fields.)

GDI typically uses the palette mapping in reverse. That is, an application specifies an RGB color for drawing and GDI must locate the color index that causes the device to display that color. As indicated in the next table, GDI provides two primary palette service functions for creating and deleting the palette, as well as some service functions related to the PALOBJ and the XLATEOBJ used to translate color indexes between two palettes.

Function

Description

EngCreatePalette

Creates a palette. The driver associates the palette with a device by returning a handle to the palette in the DEVINFO structure.

EngDeletePalette

Deletes the given palette.

PALOBJ_cGetColors

Allows a driver to download RGB colors from an indexed palette. Called by the display driver in DrvSetPalette.

XLATEOBJ_iXlate

Translates a single source color index to a destination color index.

XLATEOBJ_piVector

Retrieves a translation vector from an indexed source palette. The driver can use this vector to perform its own translation of the source indexes to destination indexes.

XLATEOBJ_cGetPalette

Retrieves the 24-bit RGB value for the colors in an indexed source palette. The driver can use this function to obtain information from the palette to perform color blending.

For more information on these functions, refer to the Graphics Driver Reference.

Palette Format	Description
Indexed	A color index is an index into an array of RGB values. The array can be small, containing, for example, 16 color indexes; or large, containing, for example, 4096 color indexes or more.
Bit Fields	Bit fields in the color index specify colors in terms of the amounts of R, G, and B in each color. For example, 5 bits could be used for each, providing a value between 0 and 31 for each color. The 5-bit value would be scaled up to cover a range of 0 to 255 for each component when converting to RGB. (The usual RGB representation itself is defined by bit fields.)

Function	Description
EngCreatePalette	Creates a palette. The driver associates the palette with a device by returning a handle to the palette in the DEVINFO structure.
EngDeletePalette	Deletes the given palette.
PALOBJ_cGetColors	Allows a driver to download RGB colors from an indexed palette. Called by the display driver in DrvSetPalette.
XLATEOBJ_iXlate	Translates a single source color index to a destination color index.
XLATEOBJ_piVector	Retrieves a translation vector from an indexed source palette. The driver can use this vector to perform its own translation of the source indexes to destination indexes.
XLATEOBJ_cGetPalette	Retrieves the 24-bit RGB value for the colors in an indexed source palette. The driver can use this function to obtain information from the palette to perform color blending.