GreRealizePalette

From EDM2
Jump to: navigation, search

GreRealizePalette is called by the Window Manager during processing of a call to WinRealizePalette. GreRealizePalette takes a logical palette and assigns it slots in the hardware palette.

This function can be hooked by the presentation driver.

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

Syntax

GreRealizePalette(hdc, pflType, pcSlotsChanged, pInstance, lFunction)

Parameters

hdc (HDC) - input
Device context handle.
pflType (PULONG) - input
Specifies whether the DC is a foreground or background window.
Used to indicate if the default colors have changed. The possible values are:
RP_BACKGROUND=0
When a palette is realized in the background (that is, the application making the WinRealizePalette call does not have the focus), then the driver should not change any entries in the hardware palette that are already mapped by other logical palettes. The presentation driver must either modify hardware palette entries that are currently unused, modify the default palette size to make additional slots available, or locate nearest color matches.
RP_FOREGROUND=1
When a logical palette is realized in the foreground (that is, the application making the WinRealizePalette call has the focus), then that palette receives priority over any other palettes that were previously realized. To satisfy the color requests of the foreground WinRealizePalette, the driver should overwrite entries in the hardware palette that are allocated to other applications, if necessary.
RP_DEFAULTSCHANGED=2
Returned by the presentation driver to indicate that all direct DCs need repainting, due to a change in the number of default system colors.
pcSlotsChanged (PULONG) - input
Pointer to the returned count of hardware slots changed.
pInstance (PVOID) - input
Pointer to instance data.
lFunction (ULONG) - input
High-order WORD=flags; low-order WORD=NGreRealizePalette.

Returns

rc (ULONG) - returns
Return codes.
On completion, this function returns the following value:
PAL-ERROR Error Number of logical palette mappings changed.
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. */
PULONG    pflType;         /*  Specifies whether the DC is a foreground or background window. */
PULONG    pcSlotsChanged;  /*  Pointer to the returned count of hardware slots changed. */
PVOID     pInstance;       /*  Pointer to instance data. */
ULONG     lFunction;       /*  High-order WORD=flags; low-order WORD=NGreRealizePalette. */
ULONG     rc;              /*  Return codes. */

rc = GreRealizePalette(hdc, pflType, pcSlotsChanged,
       pInstance, lFunction);

Remarks

If a palette has not been explicitly selected into the DC before a call to GreRealizePalette is made, the default palette is implicitly in effect and is realized.

This function requires no action for memory DCs. A call to GreRealizePalette is a real operation only when an actual device with a palette is referenced. The function does not return an error for memory DCs, therefore, an application need not be concerned with the DC type if it has a number of DCs with palettes.

When GreBitblt is performed between a memory DC and a device DC, the presentation driver has to perform the appropriate translation between the memory bit map's color table or logical palette and the physical palette.