XFree86 server 4.x Design (DRAFT) : Colormap Handling
Previous: Offscreen Memory Manager
Next: DPMS Extension

## 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 size in bits of each color component in the DAC's palette. `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-provided 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.

XFree86 server 4.x Design (DRAFT) : Colormap Handling
Previous: Offscreen Memory Manager
Next: DPMS Extension