## Display Device Driver Reference for OS/2

[prev][next][parent][TOC]

### XGA Support for Palette Management - Realizing Palettes

Applications realize their palettes using the WinRealizePalette function. This function is passed to the graphics engine and onto the presentation driver through the RealizePalette driver entry point. The driver returns values to WinRealizePalette to indicate what actions are required to keep the system consistent. This makes the RealizePalette function the heart of the Palette Manager system.

Three values are returned from the driver's RealizePalette function to WinRealizePalette:

Number of hardware palette entries changed. (A pointer to a ULONG, pcSlotsChanged, is passed as one of the function parameters).

Number of logical palette mapping indexes changed. (This is the function's return value).

Flag indicating that the default colors have changed. (A pointer to a set of flags defined as a ULONG, pflType, is passed as one of the function parameters. The flag, RP_DEFAULTSCHANGED, must be set to indicate a change in the default colors.)

The actions taken by WinRealizePalette processing depend on the return values as follows:

If the hardware palette is changed, WinRealizePalette will invalidate any saved screen bits. (See the OS/2 Presentation Device Driver Reference for details on saved screen bits).

If the hardware palette is changed and the new logical palette is being realized in the foreground, WinRealizePalette will send a WM_REALIZEPALETTE message to every application.

If the logical palette mapping indexes are changed, the number of changed indices are passed back to the application to indicate that a repaint is required.

If the default colors are changed, WinRealizePalette will invalidate the entire desktop (forcing everything to be repainted).

When a logical palette is realized in the foreground (ie, the application making the WinRealizePalette call has the focus), then that palette receives priority over any other palettes that were previously realized. To satisfy the color requests of the foreground WinRealizePalette, the driver should overwrite entries in the hardware palette that are allocated to other applications, if necessary.

If the hardware palette is changed, then all the palette mappings for the other logical palettes in the system are invalidated. The return value ( hardware palette entries changed in pcSlotsChanged) will trigger the WinRealizePalette function to send WM_REALIZEPALETTE messages to every other application. Each application will then re-realize its palette (in the background) and repaint if any of its palette color mappings differ from its previously realized mappings. As mentioned above, this is indicated by WinRealizePalette's return value.

When a palette is realized in the background (ie, the application making the WinRealizePalette call does not have the focus), then the driver should not change any entries in the hardware palette that are already mapped by other logical palettes. The presentation driver must either modify hardware palette entries that are currently unused, modify the default palette size to make additional slots available, or locate nearest color matches.

When there are no unused entries in the hardware palette for either foreground or background WinRealizePalette requests, the size of the default palette currently in use is reduced. This makes additional hardware palette entries available to logical palettes. Obviously, the minimum default palette size is 16 entries.

A valid question to ask at this point is: "What do non-palette-aware applications do when they receive a WM_REALIZEPALETTE message?" Whenever a non-palette aware application receives this message, it is not expecting it and does not know how to process it. Traditionally, these types of messages are forwarded to the default window procedure for handling. In the default window procedure, the message processing for WM_REALIZEPALETTE makes a call to realize the default palette. This is not a signal, however, to the driver to actually realize the default 256-color palette. It is a signal that the driver uses to determine when to load the appropriately sized default palette and also to determine when to increase the default palette size. This is discussed in more detail below, but we first must understand how the default palette is established, loaded and decreased in size.

The XGA display driver has a number of default palettes, of varying sizes ( as discussed above), and the realization code is responsible for determining which is the appropriate default palette to use.

Actually realizing the default palette (or rather realizing the appropriate one of the default palettes) is extremely simple. The default palette is realized whenever the foreground application requests a "realize default palette" in response to the WM_REALIZEPALETTE message, and either of the following conditions is met:

The default palette was not the last palette realized.

The size of the default palette has changed.

To realize the default palette, the data is merely copied from the first half of the appropriate default palette structure to the start of the hardware palette, and from the last half of the default palette to the end of the hardware palette. (To ensure that mixing operations form a closed set, the default palette must occupy the extreme ends of the hardware palette). The data in the default palettes is preset, so that both the RGB data and the options field can be placed directly into the hardware palette structure.

A driver enabled for seamless operation also has to consider whether it needs to force additional Windows colors into the default palette, as detailed in XGA Support for Palette Management - Seamless Modifications, below.

It is easy to determine when to move from a larger to a smaller default palette. Simply, if a logical palette is being realized which requires more slots than are currently free in the hardware palette, and the default palette is not at its minimum size, then the presentation driver should move to the next smaller default palette. This process may need to be repeated if the smaller default palette still does not provide sufficient free slots to satisfy the logical palette's requirements.

Movement through the default palettes in the opposite direction (from smaller to larger) is not nearly as straight forward.

It is not enough to simply reinstate the 256-entry default palette as soon as the driver thinks that no logical palettes are in use, since the device driver has a very poor picture of when logical palettes are in effect. (For example, assume that an image is drawn on the screen using a logical palette, but that logical palette is no longer selected into any of the display drivers' presentation spaces, perhaps because a cached-micro PS was used. Then, even though the driver is still showing the image drawn with the logical palette, the driver is unaware that the palette is still active .) Therefore, the movement through progressively larger default palettes must be based on different criteria. It is designed to be closely tied to the driver's receipt of "realize default palette" requests.

Whenever XGA is asked to realize the default palette from a foreground application, it counts the number of unused slots in the hardware palette. If there were enough free slots the last time that the default palette was realized (to allow the next larger default palette to be used), and there are still enough free slots, then the size of the default palette is increased. (It may not always be the case, however, that the number of free slots remains unchanged. Some slots could have been taken by WinRealizePalette requests from non-foreground palette aware applications. This is why there is a delay in increasing the default palette size.) Dependent on the number of free slots, the default palette size can be increased several times-until there are insufficient free slots to move to the next larger default palette, or until the maximum default palette (256 colors) is reached.

In order to prevent prematurely increasing the default palette size, whenever a logical palette is realized in the foreground, the value for "free slots the last time that the default palette was realized" is reset. This ensures that the next "realize default palette" request does not increase the size of the default palette.

If a call to realize the default palette in the foreground causes no increase in the default palette size, the XGA driver reports that there are no mapping changes, but that the hardware palette is changed. This causes the system to send WM_REALIZEPALETTE messages to all applications, and allows the driver to be notified of all logical palettes still in use. However, no repainting is needed since no color mapping changes are reported.

If realizing the default palette causes the default palette size to change, a flag is passed back to WinRealizePalette to force a repaint of the entire desktop.