GreDeviceCreatePalette

GreDeviceCreatePalette is called by GpiSelectPalette, 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

#define INCL_GRE_PALETTE
#include <os2.h>

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.