DiveSetSourcePalette
This function sets the palette associated with the source data to be used for translating from 8-bit (LUT8) format to other color formats, for example, RGB 5-6-5 or RGB24.
Syntax
_DiveSetSourcePalette(hDiveInst, ulStartIndex, ulNumEntries, pbRGB2Entries)
Parameters
- hDiveInst (HDIVE) - input
- Display engine DIVE instance.
- ulStartIndex (ULONG) - input
- Index of first palette entry to set.
- ulNumEntries (ULONG) - input
- Number of palette entries to set. If this value is **zero**, the source palette is "reset" and DiveBlitImage will no longer perform palette translations when both source and destination formats are LUT8.
- pbRGB2Entries (PBYTE) - input
- Indicates number of RGB values to be set in the source palette for use when blitting from LUT8 source format.
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 source data is invalid.
Remarks
This function is intended for use when the source data is palettized.
This function is useful for displaying LUT8 source images from applications that perform palette animation. If no source palette is specified, the OS/2 default palette values will be used for translating LUT8 source data to direct color formats. If the source and destination color formats are both LUT8 and **no source palette or no destination palette** has been set, DiveBlitImage will transfer the 8-bit image without performing any translation. If the source and destination color formats are both LUT8 and **both** palettes have been set, DiveBlitImage will perform palette translation between the source palette (associated with the source image) and the destination palette (usually the physical palette, in the case where the destination is the screen).
If DiveSetSourcePalette is not called and the source format is LUT8, then the current physical palette will be used. If DiveSetSourcePalette is not called and the source format is **not** LUT8, then the OS/2 default palette will be used.
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.
Example Code
#include <dive.h>
HDIVE hDiveInst; /* Display engine DIVE instance. */
ULONG ulStartIndex; /* First palette entry to set. */
ULONG ulNumEntries; /* Number of palette entries to set. */
PBYTE pbRGB2Entries; /* RGB values to be set. */
ULONG rc; /* Return codes. */
rc = DiveSetSourcePalette(hDiveInst, ulStartIndex,
ulNumEntries, pbRGB2Entries);