GpiQueryNearestColor

This function returns the nearest color available to the color specified on the currently associated device. Both colors are specified in RGB terms.

Syntax

GpiQueryNearestColor(hps, flOptions, lRgbIn)

Parameters

hps (HPS) - input: Presentation-space handle.

flOptions (ULONG) - input: Options.; Reserved, must be zero.

lRgbIn (LONG) - input: Required color.

Return Value

lRgbOut (LONG) - returns

Nearest available color to the one specified.

>=0: Nearest available color.
GPI_ALTERROR: Error.

Remarks

The nearest color returned is one that is available in the physical palette on the device. This might not actually be available with the currently loaded logical color table. The color returned is a pure color, that is, one that can be used for drawing lines, text, and so on. It does not take into account the possibility of dithered colors being used for filled areas. With dithering, it is likely that the color used for filling areas is different from that used for lines and text, when the same color index is selected. For a monochrome device, if lRgbIn is the reset color, then lRgbOut is also the reset color; otherwise, it is black if the reset color is white, and the converse.

Errors

Possible returns from WinGetLastError:

PMERR_INV_HPS (0x207F): An invalid presentation-space handle was specified.
PMERR_PS_BUSY (0x20F4): An attempt was made to access the presentation space from more than one thread simultaneously.
PMERR_INV_COLOR_OPTIONS (0x2057): An invalid options parameter was specified with a logical color table or color query function.
PMERR_INV_RGBCOLOR (0x20C3): An invalid rgb color parameter was specified with GpiQueryNearestColor or GpiQueryColor.

Example Code

#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>

HPS   hps;       /* Presentation-space handle. */
ULONG flOptions; /* Options. */
LONG  lRgbIn;    /* Required color. */
LONG  lRgbOut;   /* Nearest available color to the one specified. */

lRgbOut = GpiQueryNearestColor(hps, flOptions, lRgbIn);

This example uses GpiQueryNearestColor to return the nearest color available to the one specified, on the currently associated device.

#define INCL_GPILOGCOLORTABLE /* Color Table functions */
#include <os2.h>

LONG lRgbOut; /* nearest color */
HPS hps; /* Presentation-space handle */
ULONG ulOptions; /* options */
LONG lRgbIn; /* color to match */

/* reserved; set to 0 */
ulOptions = 0L;

/* color to find index for (R= 36, G= 24, B= 37) */
lRgbIn = (36*65536) + (24*256) + 37;

lRgbOut = GpiQueryNearestColor(hps, ulOptions, lRgbIn);