Difference between revisions of "GpiAnimatePalette"

Revision as of 15:44, 24 February 2020

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

Syntax

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

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