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

#define INCL_GRE_COLORTABLE
#include <os2.h>

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.