GreQueryNearestColor

GreQueryNearestColor returns the available color nearest to the specified color on the currently associated device even if it is not available in the logical color table. Both colors are specified as RGB values.

This function must be supported by the presentation driver. GreQueryNearestColor is called by GpiQueryNearestColor when the application wants the available colors nearest to the specified color.


 * Simulation support: None. This function is mandatory for all drivers.

Syntax
GreQueryNearestColor(hdc, flOptions, rgbColorIn, pInstance, lFunction);

Parameters

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


 * flOptions (ULONG) - input : Options flag.


 * The only significant flag is:


 * LCOLOPT_REALIZED: If set, the information is required when the logical color table (if any) is realized. When this flag is not set, the information is required when the logical color table is not realized.


 * Other flags are reserved.


 * rgbColorIn (LONG) - input : Color required.


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


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

Returns

 * rc (LONG) - returns : Return Code.

The handling routine must return the nearest available RGB color to that requested (rgbColorOut), or GPI_ALTERROR if an error occurred.

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_DEV_FUNC_NOT_INSTALLED
 * PMERR_INV_COLOR_OPTIONS
 * PMERR_INV_HDC
 * PMERR_INV_RGBCOLOR

Refer to the "Error Explanations" section in the Presentation Manager Programming Reference for further explanation.

Sample

 * 1) define INCL_GRE_COLORTABLE
 * 2) include 

HDC     hdc;         /*  Device context handle. */ ULONG   flOptions;   /*  Options flag. */ LONG    rgbColorIn;  /*  Color required. */ PVOID   pInstance;   /*  Pointer to instance data. */ ULONG   lFunction;   /*  High-order WORD=flags; low-order WORD=NGreQueryNearestColor. */ LONG    rc;          /*  Return Code. */

rc = GreQueryNearestColor(hdc, flOptions,      rgbColorIn, pInstance, lFunction);

Remarks
The color used for drawing primitives, such as lines and text, is the color returned. GreQueryNearestColor does not consider the possibility of using dithered colors for filling areas. Where dithered colors are used for filling, the color used for text and lines is likely to be different even when the same color index is selected.

The nearest color is determined by finding its position in RGB space. "RGB space" can be defined as a cube with three axes (representing red, green and blue color intensities) radiating from one corner or origin. Moving up the Red axis results in increasing red intensity. Different intensities of cyan can be produced by moving along the Green and Blue axes. For EGA and VGA devices, dithering is performed by dividing the RGB space into 9x9x9 cubical cells representing the colors that can be created. The cell each RGB color falls into is determined and a lookup table is created to indicate which EGA planes to set ON or OFF to create each color.

When this function is called for a monochrome device, the color returned is either the reset color or the contrast color for the device. See Support for Monochrome Devices.