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);

Related Functions