Difference between revisions of "GpiAnimatePalette"
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 |
− | + | :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''': 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''' : | + | :::'''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 | |
− | + | ::'''G''' : is green 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. | |
==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.
- F: is a flag byte, which can take the following values (these can be ORed together if required):
- 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);