PgSetPalette(), PgSetPaletteCx()

Set the color palette

Synopsis:

int PgSetPalette( PgColor_t const *palette,
                  long palette_id,
                  short first_color,
                  short num_colors,
                  int flags,
                  long tag );

int PgSetPaletteCx( PhGC_t *gc,
                    PgColor_t const *palette,
                    long palette_id,
                    short first_color,
                    short num_colors,
                    int flags,
                    long tag );

Library:

ph

Description:

These functions set the palette for subsequent draw commands. The palette can be either the graphics driver's palette, or a private hardware or software palette. The palette argument points to a static buffer containing the palette; first_color denotes the first color to set, and num_colors defines how many palette entries to set.

The graphics driver uses the palette_id tag for caching. If the palette_id is 0, the tag will be used, as long as it is not 0 as well. If palette_id and tag are both 0, your region's unique number is used as the palette ID. To have the graphics driver release a cached palette, set num_colors to -1,

A palette can operate in one of several modes. To determine the mode, set flags to one of the following:

Pg_PALSET_HARD

Used primarily for palette-based images; see PhImage_t.

Setting this palette type changes the physical palette. All colors set with a PgSet...Color() function will be chosen from this palette, for this process only. Other processes will continue to choose colors from the global palette and may appear incorrect. When you release the hardware palette, the other processes will return to their previous colors without being redrawn. You should always release the hardware palette when your window loses focus.

---

Direct-color and fixed-color graphics drivers will change this palette type to Pg_PALSET_SOFT.

---

Pg_PALSET_HARDINACTIVE

Same as Pg_PALSET_HARD, but doesn't change the physical palette. You can use this to restore the global palette.

Pg_PALSET_SOFT

Used primarily for palette-based images; see PhImage_t. Since this type is completely handled by software in the graphics driver, it doesn't affect the driver's physical palette. Colors set with this palette type are unique to your graphics context.

Pg_PALSET_HARDLOCKED

Used for palette cycling or hardware-based flashing colors. Setting this type of palette prevents set colors from being involved in automatic color selection. To access these locked colors, you should OR the index with Pg_INDEX_COLOR when setting a color value; see PgColor_t.

To ensure that no other process is currently using the specified colors, you can OR this type with Pg_PALSET_FORCE_EXPOSE—this causes the screen to redraw.

Pg_PALSET_GLOBAL

Changes the physical palette. To ensure that all processes look correct, you can OR this type with Pg_PALSET_FORCE_EXPOSE to force all windows to redraw.

You can OR the above palette types with Pg_PALSET_FORCE_EXPOSE to force an expose from the graphics driver. This is useful when changing palettes; the expose causes all applications to redraw with the new palette.

The tag argument is used for data caching by programs such as phrelay (see the QNX Neutrino Utilities Reference). To calculate the tag, use PtCRC(). This argument is ignored if you set it to 0.

PgSetPalette() works on the current graphics context, while you can specify the graphics context gc for PgSetPaletteCx().

Returns:

0

Success.

-1

The draw buffer is too small to hold the current draw state and the draw command.

Classification:

Photon

See also:

PgColor_t PgDrawImage*(), PgSetFillColor*(), PgSetStrokeColor*(), PgSetTextColor*(), PhImage_t, PtCRC()

“Drawing attributes” in the Raw Drawing and Animation chapter of the Photon Programmer's Guide