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.
