View source for DiveSetSourcePalette

{{DISPLAYTITLE: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==
<PRE>
#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);
</PRE>

== Related Methods==
* [[DiveSetDestinationPalette]]

[[Category:Dive]]