A generic colormap handling layer is provided within the XFree86 common
layer. This layer takes care of most of the details, and only requires
a function from the driver that loads the hardware palette when required.
To use the colormap layer, a driver calls the
xf86HandleColormaps() function.
Bool xf86HandleColormaps(ScreenPtr pScreen, int maxColors,
int sigRGBbits, LoadPaletteFuncPtr loadPalette,
SetOverscanFuncPtr setOverscan, unsigned int flags)This function must be called after the default colormap has been initialised. The
pScrn->gammafield must also be initialised, preferably by callingxf86SetGamma().maxColorsis the number of entries in the palette.sigRGBbitsis the size in bits of each color component in the DAC's palette.loadPaletteis a driver-provided function for loading a colormap into the hardware, and is described below.setOverscanis an optional function that may be provided when the overscan color is an index from the standard LUT and when it needs to be adjusted to keep it as close to black as possible. ThesetOverscanfunction programs the overscan index. It shouldn't normally be used for depths other than 8.setOverscanshould be set toNULLwhen it isn't needed.flagsmay be set to the following (which may be ORed together):
CMAP_PALETTED_TRUECOLORthe TrueColor visual is paletted and is just a special case of DirectColor. This flag is only valid for
bpp > 8.
CMAP_RELOAD_ON_MODE_SWITCHreload the colormap automatically after mode switches. This is useful for when the driver is resetting the hardware during mode switches and corrupting or erasing the hardware palette.
CMAP_LOAD_EVEN_IF_OFFSCREENreload the colormap even if the screen is switched out of the server's VC. The palette is not reloaded when the screen is switched back in, nor after mode switches. This is useful when the driver needs to keep track of palette changes.
The colormap layer normally reloads the palette after VT enters so it is not necessary for the driver to save and restore the palette when switching VTs. The driver must, however, still save the initial palette during server start up and restore it during server exit.
void LoadPalette(ScrnInfoPtr pScrn, int numColors, int *indices,
LOCO *colors, VisualPtr pVisual)
LoadPalette()is a driver-provide function for loading a colormap into hardware.colorsis the array of RGB values that represent the full colormap.indicesis a list of index values into the colors array. These indices indicate the entries that need to be updated.numColorsis the number of the indices to be updated.
void SetOverscan(ScrnInfoPtr pScrn, int overscan)
SetOverscan()is a driver-provided function for programming theoverscanindex. As described above, it is normally only appropriate for LUT modes where all colormap entries are available for the display, but where one of them is also used for the overscan (typically 8bpp for VGA compatible LUTs). It isn't required in cases where the overscan area is never visible.