GpiCreatePalette
Description
This function creates and initializes a color palette.
Syntax
#define INCL_GPILOGCOLORTABLE /* Or use INCL_GPI, INCL_PM, */
#include <os2.h>
HAB hab; /* Anchor-block handle. */
ULONG flOptions; /* Options. */
ULONG ulFormat; /* Format of entries in the table. */
ULONG ulCount; /* Count of elements in aulTable. */
PULONG aulTable; /* Start of the application data area. */
HPAL hpal; /* Palette handle. */
hpal = GpiCreatePalette(hab, flOptions, ulFormat,
ulCount, aulTable);
Parameters
- hab (HAB) - input
- Anchor-block handle.
- flOptions (ULONG) - input
- Options.
To combine the following two options, OR the values together. Other flags are reserved and must be 0.
LCOL_PURECOLOR : The application does not want color dithering to create colors not available in the physical palette for solid patterns (see GpiSetPattern). If this option is set, only pure colors are used and no dithering is done.
LCOL_OVERRIDE_DEFAULT_COLORS : Override option for applications that need the full hardware palette. The system does not guarantee a consistent look to the user interface when this option is used. The override is only in effect while the overriding palette is in the foreground.
- ulFormat (ULONG) - input
- Format of entries in the table.
It must be the following value:
LCOLF_CONSECRGB : Array of (RGB) values. Each entry is 4 bytes long. This is currently the only supported value for this parameter.
- ulCount (ULONG) - input
- Count of elements in aulTable.
This must be greater than 0.
- aulTable (PULONG) - input
- Start of the application data area.
This contains the palette definition data.
Each color value is a 4-byte integer, with a value of
(F * 16777216) + (R * 65536) + (G * 256) + B
where:
- F is a flag byte, which can take the following values (these can be ORed together if required):
PC_RESERVED : This index is an animating index. This means that the application might frequently change the RGB value and so the system should not map the logical index of the palette of another application to the entry in the physical palette used for this color.
PC_EXPLICIT : The low-order word of the logical color table entry designates a physical palette slot from which the color definition is to be taken. This allows an application to show the actual contents of the device palette as realized for other logical palettes. This does not prevent the color in the slot from being changed for any reason.
R is red intensity value G is green intensity value B is blue intensity value.
Each intensity value must be in the range 0 through 255.
- hpal (HPAL) - returns
- Palette handle.
<>0 Palette handle GPI_ERROR Error occurred.
Return Code
hpal (HPAL) - returns
Palette handle.
<>0 Palette handle GPI_ERROR Error occurred.
Errors
Possible returns from WinGetLastError
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_INSUFFICIENT_MEMORY (0x203E)
The operation terminated through insufficient memory.
Remarks
The new palette contains only the entries set in the aulTable parameter. All color indices outside this range are not considered part of the palette; it is an error to use such colors when this palette is selected.
When a palette is realized (see WinRealizePalette in the Presentation Manager Programming Reference) the lowest indices are considered first. The palette should therefore be ordered so that the most important colors have the lowest indices. Animating indices, which on realization can have their own individual slots in the physical palette, should be used only when necessary.
Palettes should be created with only those color indices that the application requires and not unnecessarily create a large palette. The maximum index for a palette is not limited to CAPS_COLOR_INDEX.
The palette can be selected into a presentation space using GpiSelectPalette.
Example Code
The uses GpiCreatePalette to create and initialize a palette of 4 pure (no dithering) colors.
#define INCL_GPILOGCOLORTABLE /* Color Table functions */
#include <os2.h>
HAB hab; /* anchor block handle */
HPAL hpal; /* palette handle */
LONG lFormat; /* table entry format */
/*****************************************************************
* assume 4 entries in palette. *
* The RGB values are calculated with the following formula: *
* (F * 16777216) + (R * 65536) + (G * 256) + B *
* where F = flag, PC_RESERVED or PC_EXPLICIT *
* R = red intensity value *
* G = green intensity value *
* B = blue intensity value *
* Thus, in the following table, red and green intensities are 0 *
* while the blue intensity increases from 1 to 4. *
*****************************************************************/
ULONG aulTable[4]=
{(PC_RESERVED*16777216) + (0*65536) + (0*256) + 1,
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 2,
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 3,
(PC_RESERVED*16777216) + (0*65536) + (0*256) + 4};
hpal = GpiCreatePalette(hab, 0L, LCOLF_CONSECRGB, 4L, aulTable);