13. Colormap Handling

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->gamma field must also be initialised, preferably by calling xf86SetGamma(). maxColors is the number of entries in the palette. sigRGBbits is the number of significant bits in each colour component. This would normally be the same as pScrn->rgbBits. loadPalette is a driver-provided function for loading a colormap into the hardware, and is described below. setOverscan is 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. The setOverscan function programs the overscan index. It shouldn't normally be used for depths other than 8. setOverscan should be set to NULL when it isn't needed. flags may be set to the following (which may be ORed together):

CMAP_PALETTED_TRUECOLOR

the TrueColor visual is paletted and is just a special case of DirectColor. This flag is only valid for bpp > 8.

CMAP_RELOAD_ON_MODE_SWITCH

reload 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_OFFSCREEN

reload 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. colors is the array of RGB values that represent the full colormap. indices is a list of index values into the colors array. These indices indicate the entries that need to be updated. numColors is the number of the indices to be updated.

void SetOverscan(ScrnInfoPtr pScrn, int overscan)

SetOverscan() is a driver-provided function for programming the overscan index. 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.