Difference between revisions of "GpiAnimatePalette"

From EDM2
Jump to: navigation, search
m (Related Functions)
m
 
Line 5: Line 5:
  
 
==Parameters==
 
==Parameters==
;hpal (HPAL) - input : Palette handle.
+
;hpal (HPAL) - input: Palette handle.
;ulFormat (ULONG) - input : Format of entries in the table.
+
;ulFormat (ULONG) - input: Format of entries in the table.
:It must be the following value:
+
:It must be the following value: LCOLF_CONSECRGB
LCOLF_CONSECRGB
+
:Array of RGB values, corresponding to color indexes ulStart upwards. Each entry is 4 bytes long.
:Array of RGB values, corresponding to color indexes ulStart upwards. Each entry is 4 bytes long.  
+
;ulStart (ULONG) - input: Starting index.
;ulStart (ULONG) - input : Starting index.
+
 
:This is relevant only for LCOLF_CONSECRGB.
 
:This is relevant only for LCOLF_CONSECRGB.
;ulCount (ULONG) - input : Count of elements in aulTable.
+
;ulCount (ULONG) - input: Count of elements in aulTable.
 
:This must be greater than or equal to 0.
 
:This must be greater than or equal to 0.
; aulTable (PULONG) - input : Start of the application data area.
+
; aulTable (PULONG) - input: Start of the application data area.
 
:This contains the palette definition data. The format depends on the value of ulFormat.
 
: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
+
:Each color value is a 4-byte integer, with a value of <tt>(F * 16777216) + (R * 65536) + (G * 256) + B</tt> where:
(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):
 
::'''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_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.
+
:::'''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
+
::'''R''' : is red intensity value
:::'''G''' : is green intensity value
+
::'''G''' : is green intensity value
:::'''B''' : is blue intensity value
+
::'''B''' : is blue intensity value
 
::The maximum intensity for each primary is 255.
 
::The maximum intensity for each primary is 255.
 
;lChanged (LONG) - returns : Number of remapped colors.
 
;lChanged (LONG) - returns : Number of remapped colors.
:'''PAL_ERROR''' : Error occurred  
+
:'''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.
+
:'''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.
+
;Note:By the time an application receives this information, other applications using the palette may have caused the number to be changed.
  
 
==Returns==
 
==Returns==
;lChanged (LONG) - returns : Number of remapped colors.
+
;lChanged (LONG) - returns: Number of remapped colors.
PAL_ERROR  - Error occurred
+
*PAL_ERROR  - Error occurred
 
+
*Other - Number of colors remapped (that is, having entries in the physical color table).
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.
 
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.
+
;Note: By the time an application receives this information, other applications using the palette may have caused the number to be changed.
  
 
==Errors==
 
==Errors==
Line 64: Line 60:
 
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.
 
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.
+
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.
 
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.
+
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.
 
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.  
+
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==
 
==Example Code==

Latest revision as of 21:29, 23 May 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

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