DiveSetDestinationPalette
This function sets the palette associated with the destination of DiveBlitImage. This capability is useful for outputting direct color image formats on 8-bit (256) displays. If no destination palette has been set, direct color space to LUT8 color-space conversion will be performed assuming the destination palette is the standard OS/2 palette. If DIVE is being used to transfer direct color images to an 8-bit display and the physical palette changes, it is expected that the application will provide notification of the change to the DIVE instance using this function.
Syntax
_DiveSetDestinationPalette(hDiveInst, ulStartIndex, ulNumEntries, pbRGB2Entries)
Parameters
- hDiveInst (HDIVE) - input
- Display engine DIVE instance.
- ulStartIndex (ULONG) - input
- Starting location of the palette changes; usually 0.
- ulNumEntries (ULONG) - input
- Number of entries of palette change; usually 256.
- pbRGB2Entries (PBYTE) - input
- Indicates the palette for the target image space. This does not set the physical palette.
Returns
- rc (ULONG) - returns
- Return codes indicating success or type of failure:
- DIVE_SUCCESS If the function succeeds, 0 is returned.
- DIVE_ERR_INVALID_INSTANCE The DIVE instance handle specified in the hDiveInst parameter is invalid.
- DIVE_ERR_INVALID_PALETTE The palette specified for the destination data is invalid.
Remarks
Neither DiveSetSourcePalette nor **DiveSetDestinationPalette** will set the physical palette. If your application needs to set the physical palette (that is, all 256 entries), it must do so as a full-screen (maximized) application. No WM_REALIZEPALETTE message will be sent to other applications, and no redraw is done.
If **DiveSetDestinationPalette** is not called and the display resolution is LUT8, then the current physical palette will be used. If **DiveSetDestinationPalette** is not called and the display resolution is **not** LUT8, then the OS/2 default palette will be used.
Most applications will notify DIVE of a physical palette change when a WM_REALIZEPALETTE message comes in on the message queue. You need not query the palette in this scenario, as a call to `DiveSetDestinationPalette( hDiveInst, 0, 256, 0 )` will query the physical palette for the application.
Example Code
#include <dive.h>
HDIVE hDiveInst; /* Display engine DIVE instance. */
ULONG ulStartIndex; /* Index of first palette entry to set. */
ULONG ulNumEntries; /* Number of palette entries to set. */
PBYTE pbRGB2Entries; /* Palette for target image space. */
ULONG rc; /* Return codes. */
rc = DiveSetDestinationPalette(hDiveInst,
ulStartIndex, ulNumEntries, pbRGB2Entries);