GpiAnimatePalette

Description

This function changes the color values of animating indexes in a palette.

Syntax

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

HPAL      hpal;      /*  Palette handle. */
ULONG     ulFormat;  /*  Format of entries in the table. */
ULONG     ulStart;   /*  Starting index. */
ULONG     ulCount;   /*  Count of elements in aulTable. */
PULONG    aulTable;  /*  Start of the application data area. */
LONG      lChanged;  /*  Number of remapped colors. */

lChanged = GpiAnimatePalette(hpal, ulFormat,ulStart, ulCount, aulTable);

Parameters

hpal (HPAL) - input

Palette handle.

ulFormat (ULONG) - input

Format of entries in the table.

It must be the following value:

   LCOLF_CONSECRGB
       Array of RGB values, corresponding to color indexes ulStart upwards. Each entry is 4 bytes long. 

ulStart (ULONG) - input

Starting index.

This is relevant only for LCOLF_CONSECRGB.

ulCount (ULONG) - input

Count of elements in aulTable.

This must be greater than or equal to 0.

aulTable (PULONG) - input

Start of the application data area.

This contains the palette definition data. The format depends on the value of ulFormat.

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, 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 entry. This allows an application to show the contents of the device palette as realized for other logical palettes. This does not prevent the color in the entry from being changed for any reason.

R : is red intensity value

G : is green intensity value

B : is blue intensity value.

The maximum intensity for each primary is 255.

lChanged (LONG) - returns

Number of remapped colors.

PAL_ERROR : Error occurred

Other : Number of colors remapped (that is, having entries in the physical color table). These are all animating indexes: they have the PC_RESERVED flag set on this function. If the palette is selected into more than one presentation space, the number returned is the maximum number of indexes that have entries in any of the relevant devices.

Note: By the time an application receives this information, other applications using the palette may have caused the number to be changed.

Returns

lChanged (LONG) - returns

Number of remapped colors.

   PAL_ERROR
       Error occurred Other
       Number of colors remapped (that is, having entries in the physical color table). These are all animating indexes: they have the PC_RESERVED flag set on this function. If the palette is selected into more than one presentation space, the number returned is the maximum number of indexes that have entries in any of the relevant devices.

       Note: By the time an application receives this information, other applications using the palette may have caused the number to be changed. 

Errors

Possible returns from WinGetLastError

0x203E	PMERR_INSUFFICIENT_MEMORY	The operation terminated through insufficient memory.
0x2054	PMERR_INV_COLOR_DATA	Invalid color table definition data was specified with GpiCreateLogColorTable.
0x2055	PMERR_INV_COLOR_FORMAT	An invalid format parameter was specified with GpiCreateLogColorTable.
0x2058	PMERR_INV_COLOR_START_INDEX	An invalid starting index parameter was specified with a logical color table or color query function.
0x2085	PMERR_INV_IN_AREA	An attempt was made to issue a function invalid inside an area bracket. This can be detected while the actual drawing mode is draw or draw-and-retain or during segment drawing or correlation functions.
0x2092	PMERR_INV_LENGTH_OR_COUNT	An invalid length or count parameter was specified.
0x2111	PMERR_INV_HPAL	An invalid color palette handle was specified.
0x2112	PMERR_PALETTE_BUSY	An attempt has been made to reset the owner of a palette when it was busy.

Remarks

The animating indexes are those that have the PC_RESERVED flag set in the palette and also in the corresponding element of the aulTable array in this function.

If an animating index already has an entry in the physical hardware palette (allocated from a previous call to WinRealizePalette), both that entry and the entry in the logical palette are changed. If there is not an entry in the physical palette, or the device does not support palette functions, the logical palette color is changed. This function does not allocate a new entry in the physical palette.

This function ignores those elements in aulTable corresponding to non-animating indexes (those that do not have the PC_RESERVED flag set). Their colors are not changed.

All presentation spaces that have this palette selected into them (see GpiSelectPalette) are updated with the effects of this function. It is not necessary to issue a WinRealizePalette function before the effects become visible.

If a palette is selected into a presentation space that is associated with a device context of type OD_METAFILE or OD_METAFILE_NOQUERY, only the final color values are recorded in the metafile.

It is an error if a palette is selected into a presentation space that is within an area or path definition when this function is issued.

Example Code

This example uses GpiAnimatePalette to change the color values of the first four animating indexes in a palette.

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

LONG  lremapColors;     /* number of remapped colors            */
HPAL  hpal;             /* palette handle                       */

/*****************************************************************
 * 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};


lremapColors = GpiAnimatePalette(hpal, LCOLF_CONSECRGB, 0L, 4L, aulTable);

Related Functions

• GpiCreatePalette
• GpiDeletePalette
• GpiQueryPalette
• GpiQueryPaletteInfo
• GpiSelectPalette
• GpiSetPaletteEntries