View source for GpiCreateLogColorTable

This function defines the entries of the logical color table.

== Syntax == 
 GpiCreateLogColorTable(hps, flOptions, lFormat, lStart, lCount, alTable)

== Parameters ==
;hps (HPS) - input:Presentation-space handle.
;flOptions (ULONG) - input:Options.
:This parameter can have one of the following values or 0:
::LCOL_RESET
:::The color table is reset to its default values before processing the remainder of the data in this function.
:::This value is assumed if the color table is currently in RGB mode and is being changed to index mode; that is, LCOLF_INDRGB or LCOLF_CONSECRGB is specified.
:::The lFormat parameter must be LCOLF_INDRGB or LCOLF_CONSECRGB.
::LCOL_PURECOLOR
:::When this option is set only colors for solid patterns (see GpiSetPattern) available in the physical palette will be used. Only pure colors are used and no dithering is done.
::Other flags are reserved and must be 0.
;lFormat (LONG) - input:Format of entries in the table.
:This parameter can have one of the following values:
::LCOLF_INDRGB 
:::Array of index/RGB pairs. Each pair is 8 bytes long: 4 bytes (local format) for the index, and 4 bytes for the color value.
:::This sets the color table into index mode (and forces LCOL_RESET) if it is in RGB mode. 
:::The maximum index that can be loaded is returned in the CAPS_COLOR_INDEX parameter of the DevQueryCaps function.
::Each index specified must be greater than or equal to 0.
::See [[DevQueryCaps]] in the ''Presentation Manager Programming Reference'' for more information.
::LCOLF_CONSECRGB
:::Array of RGB values, corresponding to color indexes lStart upwards. Each entry is 4 bytes long.
:::This sets the color table into index mode (and forces LCOL_RESET) if it is in RGB mode.
:::The maximum index that can be loaded is returned in the CAPS_COLOR_INDEX parameter of the DevQueryCaps function.
::LCOLF_RGB
:::Color index = RGB.
:::This sets the color table into RGB mode.
;lStart (LONG) - input:Starting index.
:This is relevant only for LCOLF_CONSECRGB.
:The starting index must be greater than or equal to 0.
;lCount (LONG) - input:Count of elements in alTable.
:This must be greater than or equal to 0. If 0 is specified, LCOLF_INDRGB and LCOLF_CONSECRGB have the same effect.
:For LCOLF_INDRGB, alTable must contain an even number of elements. lCount must be an even number.
;alTable (PLONG) - input:Start of the application data area.
:This contains the color table definition data. The format depends on the value of lFormat.
:Each color value is a 4-byte integer, with a value of
::(R * 65536) + (G * 256) + B
:where:
::R is red intensity value 
::G is green intensity value
::B is blue intensity value. The maximum intensity for each primary is 255.
:The high order byte must be 0.

== Returns ==
;rc (BOOL) - returns
:Success indicator.
:*TRUE  - Successful completion
:*FALSE - Error occurred.

==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_LENGTH_OR_COUNT (0x2092) An invalid length or count parameter was specified.
:PMERR_INV_COLOR_DATA (0x2054) Invalid color table definition data was specified with GpiCreateLogColorTable.
:PMERR_INV_COLOR_FORMAT (0x2055) An invalid format parameter was specified with GpiCreateLogColorTable.
:PMERR_INV_COLOR_START_INDEX (0x2058) An invalid starting index parameter was specified with a logical color table or color query function.
:PMERR_REALIZE_NOT_SUPPORTED (0x20F7) An attempt was made to create a realizable logical color table on a device driver that does not support this function.
:PMERR_PALETTE_SELECTED (0x210F) Color palette operations cannot be performed on a presentation space while a palette is selected.

== Sample ==
This example uses the GpiCreateLogColorTable function to create a logical color table, using data from the previous logical color table.
<pre>
#define INCL_GPILOGCOLORTABLE   /* Color Table functions        */
#include <os2.h>

HPS hps;                /* presentation space handle            */
LONG alTable[16];       /* assume 16 entries                    */

/* retrieve the current table */

GpiQueryLogColorTable(hps, 0L, 0L, 16L, alTable);

alTable[1] = 0x000080; /* change the second entry to light blue */

GpiCreateLogColorTable(hps,         /* presentation space       */
    0L,                             /* no special options       */
    LCOLF_CONSECRGB,                /* consecutive RGB values   */
    0L,                             /* start with color index 0 */
    16,                             /* 16 entries               */
    alTable);                       /* RGB color values         */
</pre>

== Remarks ==
This function can cause the color table to be reset to the default values. These are:
:CLR_BACKGROUND Reset color, used by [[GpiErase]]. This is the natural background color for the device. For a display, it is the default window color (SYSCLR_WINDOWTEXT; see [[WinSetSysColors]] in the ''Presentation Manager Programming Reference''). For a printer, it is the paper color.

The background color for the display can be changed by setting new system colors from the Control Panel. The background color for a printer can be changed by selecting a new paper color (if allowed by the presentation driver).
:CLR_BLUE Blue.
:CLR_RED Red.
:CLR_PINK Pink (magenta).
:CLR_GREEN Green.
:CLR_CYAN Cyan (turquoise).
:CLR_YELLOW Yellow.
:CLR_NEUTRAL A device-dependent color that provides a contrasting color to CLR_BACKGROUND. For a display, it is the default window text color (SYSCLR_WINDOWTEXT; see WinSetSysColors). For a printer, it is a color that contrasts with the paper color.

The neutral color for the display can be changed by setting new system colors from the Control Panel. The neutral color for a printer can be changed by selecting a new paper color (if allowed by the presentation driver).
:CLR_DARKGRAY Dark gray.
:CLR_DARKBLUE Dark blue.
:CLR_DARKRED Dark red.
:CLR_DARKPINK Dark pink.
:CLR_DARKGREEN Dark green.
:CLR_DARKCYAN Dark cyan.
:CLR_BROWN Brown.
:CLR_PALEGRAY Pale gray.
GpiErase clears the output of a device to the color defined by CLR_BACKGROUND.

By default, presentation spaces have a logical color table consisting of the 16 default values given above. In index mode, these entries are always considered as part of the color table, unless they are explicitly overwritten. Color indexes outside this range, which have not been loaded, are not considered as part of the color table; it is an error to use such colors if the color table is in index mode.

The system performs a mapping from the colors in the logical color table to those in the standard physical color table for that device. This mapping is used for all drawing and bit maps. Mixing is not predictable.

The standard physical color table always includes the standard 16 colors, where this is physically possible. On devices that support more than 16 colors, there may be additional colors available to which the requested colors may be mapped. However, it cannot be ensured that these additional colors are the same on different devices. Applications that depend upon precise colors beyond the first 16 should use a palette (see GpiCreatePalette) on devices for which this is supported. DevQueryCaps can be used to determine whether the function is supported by the device; see CAPS_PALETTE_MANAGER.

For a monochrome device (whether it is a display, bit map, printer, or some other type), a reset color is defined as follows:
#Start with the appropriate item below:
#*The paper color, for a printer with no loaded color table
#*SYSCLR_WINDOW for a monochrome display with no loaded color table
#*Color 0, for any device if a color table has been loaded.
#If this color is white or a light color, the reset color is set to white; otherwise, the reset color is set to black.

The reset color is used for:
*The color that GpiErase clears the output to
*CLR_BACKGROUND (color 0), unless an RGB color table is in use
*CLR_DEFAULT for GpiSetBackColor
*Any color that has exactly the same RGB value as the reset color.
Any other color becomes black if the reset color is white, and the converse.

Note: There are restrictions on the use of this function when creating SAA-conforming metafiles; see "MetaFile Resolutions" in the ''Presentation Manager Programming Reference'' for more information.

== Related Functions ==
* [[GpiCreatePalette]]
* GpiQueryColorData
* GpiQueryColorIndex
* GpiQueryLogColorTable 
* GpiQueryNearestColor
* GpiQueryRealColors
* GpiQueryRGBColor

[[Category:Gre]]