GreDeviceCreatePalette

GreDeviceCreatePalette is called by GreSelectPalette, to process an application's GpiSelectPalette request. The presentation driver is expected to perform any allocation and data structure initialization needed for a subsequent GreDeviceRealizePalette to succeed.

This function can be hooked by the presentation driver.


 * Simulation support: This function is simulated by a handling routine in Revision 2.0 (or later) of the graphics engine.

Syntax
GreDeviceCreatePalette(hdc, ppalinfo, hdevpal, pInstance, lFunction);

Parameters

 * hdc (HDC) - input
 * Device context handle.


 * ppalinfo (PPALETTEINFO) - input
 * Pointer to table of palette data.


 * Pointer to table of palette data from GreCreatePalette. The structure of palinfo is as follows:

struct _PALETTEINFO { /* palinfo */

ULONG       flCmd;         /* Options from create                   */ ULONG       ulFormat;      /* Specifies format of entries at create */ /* Must be LCOLF-CONSECRGB              */ ULONG       clColorData;   /* Count of Palette entries              */ RGB2  argb[0];             /* Palette entries                       */

} PALETTEINFO; Additional RGB@ entries follow so that CLColorData-1 entries are defined.


 * hdevpal (ULONG) - input
 * Device palette handle (NULL, if new).


 * If hdevpal=0, ppalinfo points to a palette information structure, which must be set into a new palette. The handle for this new palette is returned in hdevpal. The new palette is then selected into the DC.


 * If hdevpal is nonzero, ppalinfo is ignored, the palette is selected into the DC, and hdevpal is a device palette handle previously returned by the presentation driver. In this case, hdevpal is used to bind the palette with the new DC. This technique is the driver-level mechanism for sharing palettes among contexts on the same device.


 * pInstance (PVOID) - input
 * Pointer to instance data.


 * lFunction (ULONG) - input
 * High-order WORD=flags; low-order WORD=NGreDeviceCreatePalette.

Returns

 * rc (ULONG) - returns
 * Return codes.


 * On completion, this function returns the handle to the device palette (hdevpal).


 * Possible Errors Detected: When an error is detected, the handling routine must call WinSetErrorInfo to post the condition. Error codes for conditions that the handling routine is expected to check include:


 * PMERR_INV_IN_AREA
 * PMERR_INV_IN_PATH

Sample

 * 1) define INCL_GRE_PALETTE
 * 2) include 

HDC            hdc;        /*  Device context handle. */ PPALETTEINFO   ppalinfo;   /*  Pointer to table of palette data. */ ULONG          hdevpal;    /*  Device palette handle (NULL, if new). */ PVOID          pInstance;  /*  Pointer to instance data. */ ULONG          lFunction;  /*  High-order WORD=flags; low-order WORD=NGreDeviceCreatePalette. */ ULONG          rc;         /*  Return codes. */

rc = GreDeviceCreatePalette(hdc, ppalinfo,      hdevpal, pInstance, lFunction);

Remarks
When an application sets a bit map, the bits are specified as indexes into the color table supplied with the bit map. The presentation driver allocates its own copy of the bit map.

The driver-level pels contain indexes to the nearest color in the default physical palette.


 * Note: This means that GreGetBitMapBits does not necessarily return the same bit map that the application set. Information may be lost if the bit map is taken to a less color-capable system and then brought back to the (more capable) system on which it was created.

However, an application can select a palette into a memory DC. This causes the color table and the bit-map bits to change to the nearest mapping to the new palette. Calls to GreRealizePalette are not performed on memory DCs. The palette takes effect as soon as it is selected.

The presentation driver is expected to perform any allocation and data structure needed for a subsequent GreDeviceResizePalette to succeed.