GreCreateLogColorTable

GreCreateLogColorTable defines the entries of the Logical Color Table.

This function must be supported by the presentation driver. GreCreateLogColorTable is called by GpiCreateLogColorTable to create a Logical Color Table, which is used in subsequent drawing operations.

Simulation support

None. This function is mandatory for all drivers.

Syntax

GreCreateLogColorTable(hdc, flOptions, lFormat, lStart, cCount, pData, pInstance, lFunction)

Parameters

hdc (HDC) - input

Device context handle.

flOptions (ULONG) - input

Options flag.

Valid options are:

LCOL_RESET

Indicates that the handling routine must reset the color table to default before processing the remainder of this function.

Note

This option is assumed when the color table is changed from LCOLF_RGB to LCOLF_INDRGB or LCOLF_CONSECRGB.

LCOL_REALIZABLE

Indicates that the application can call GreRealizeColorTable at the appropriate time. This can affect the way the handling routine maps the indexes when the Logical Color Table is not realized. A realizable color table is only required to provide color mapping for its color indexes while it is realized.

If this flag is not set, GreRealizeColorTable has no effect and posts a warning.

LCOL_PURECOLOR

For solid patterns, pattern colors that are not available can be approximated by dithering. When this flag is set, only pure colors are used; the handling routine must not dither colors. The default is to allow color dithering.

Other flags are reserved and must be 0.

lFormat (LONG) - input

Format of entries in the table.

Valid formats are:

LCOLF_INDRGB: Array of (index, RGB) values. Each pair of values contains eight bytes, a four-byte index and a four-byte color. This flag sets the color table into index mode, and forces LCOL_RESET if it is in RGB mode.

LCOLF_CONSECRGB: Array of (RGB) values corresponding to color indexes starting from lStart upwards. Each entry is a four-byte value. This flag sets the color table into index mode, and forces LCOL_RESET if it is in RGB mode.

LCOLF_RGB: Color index = RGB. This flag sets the color table to RGB mode.

lStart (LONG) - input

Starting index.

Starting index. Only relevant when lFormat is set to LCOLF_CONSECRGB.

cCount (LONG) - input

Number of elements supplied in the application data area.

The number of elements supplied in pData. This flag can be set to 0 if the color table is to be reset to the default or LCOLF_RGB. When this is 0, LCOLF_INDRGB and LCOLF_CONSECRGB have the same effect.

For LCOLF_INDRGB, cCount must be an even number.

pData (PLONG) - input

Pointer to the application data area.

Pointer to the data area containing the color table definition data. The format depends on the value of lFormat. Each color value is a four-byte integer with a value of:

(R*65536) + (G*256) + B

Where:

 R = red color intensity value
 G = green color intensity value
 B = blue color intensity value

The maximum intensity for each primary is 255.

pInstance (PVOID) - input

Pointer to instance data.

lFunction (ULONG) - input

High-order WORD=flags; low-order WORD=NGreCreateLogColorTable.

Returns

rc (BOOL) - returns

Return Codes.

On completion, the handling routine must return a BOOLEAN value to indicate success or an error.

• TRUE Successful
• FALSE Error

Possible Errors Detected: Error checking for this function is performed by the graphics engine. Error codes for conditions the handling routine can expect to be passed by the graphics engine include:

• PMERR_DEV_FUNC_NOT_INSTALLED
• PMERR_INSUFFICIENT_MEMORY
• PMERR_INV_COLOR_DATA
• PMERR_INV_COLOR_FORMAT
• PMERR_INV_COLOR_INDEX
• PMERR_INV_COLOR_START_INDEX
• PMERR_INV_HDC
• PMERR_INV_IN_AREA
• PMERR_INV_IN_PATH
• PMERR_INV_LENGTH_OR_COUNT
• PMERR_REALIZE_NOT_SUPPORTED

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     lFormat;    /*  Format of entries in the table. */
LONG     lStart;     /*  Starting index. */
LONG     cCount;     /*  Number of elements supplied in the application data area. */
PLONG    pData;      /*  Pointer to the application data area. */
PVOID    pInstance;  /*  Pointer to instance data. */
ULONG    lFunction;
BOOL     rc;         /*  Return Codes. */

rc = GreCreateLogColorTable(hdc, flOptions,
       lFormat, lStart, cCount, pData, pInstance, lFunction);

Remarks

Refer to the function "GpiCreateLogColorTable" in the Presentation Manager Programming Reference for more information.