Legacy Mac OS X Reference Library Apple Developer Connection

Legacy Documentclose button

Important: The Palette Manager is deprecated as of Mac OS X v10.4. There is no replacement.


Palette Manager Reference (Not Recommended)

Framework
ApplicationServices/ApplicationServices.h
Declared in
Palettes.h

Overview

Important: The Palette Manager is deprecated as of Mac OS X v10.4. There is no replacement.

Prior to Mac OS X, applications could use the Palette Manager to ensure that the best set of colors is available when drawing to displays with limited color capabilities (pixel depth of 8 bits or less). For applications running in Mac OS X, the Palette Manager is no longer relevant because display devices always support direct color (pixel depth of 16 or 32 bits). The palette-based graphics model only works in 256-color (8-bit pseudocolor) modes of operation, which are not supported for the Mac OS X GUI.

There is some support for palettes in Quartz Services; see Quartz Display Services Reference.

Functions by Task

Function descriptions are grouped by programming task. For an alphabetical list of functions, see the API index.

Animating Palettes

Changing the Pixel Depth for a Video Device

Drawing With Color Palettes

Initializing and Allocating Palettes

Initializing the Palette Manager

Interacting With the Window Manager

Manipulating Palette Entries

Manipulating Palettes and Color Tables

Miscellaneous

Data Types

ColorInfo

Specifies color information for each color in a palette.

struct ColorInfo {
   RGBColor ciRGB;
   short ciUsage;
   short ciTolerance;
   short ciDataFields[3];
};
typedef struct ColorInfo ColorInfo;
typedef ColorInfo * ColorInfoPtr;
Fields
ciRGB

An RGB color value, which is defined by the RGBColor structure. It contains three fields that contain integer values for defining, respectively, the red, green, and blue values of the color.

ciUsage

One or more of the usage constants, specifying how this entry is to be used. The ciUsage field can contain any of the Usage Constants.

ciTolerance

An integer expressing the range in RGB space within which the red, green, and blue values must fall to satisfy this entry. A tolerance value of $0000 means that only an exact match is acceptable. Values of $0xxx other than $0000 are reserved and should not be used in applications.

ciDataFields

Private fields.

Discussion

Each color information structure in a palette comprises an RGB color value, information describing how the color is to be used, a tolerance value for colors that need only be approximated, and private fields. You should not create and modify the public fields directly; instead, use Palette Manager functions such as SetEntryColor and SetEntryUsage.

Availability
Declared In
Palettes.h

Palette

Represents a set of colors optimized for use on display devices with a limited number of colors.

struct Palette {
   short pmEntries;
   short pmDataFields[7];
   ColorInfo pmInfo[1];
};
typedef struct Palette Palette;
typedef Palette * PalettePtr;
Fields
pmEntries

The number of ColorInfo structures in the pmInfo array.

pmDataFields

Private fields used by the Palette Manager.

pmInfo

An array of ColorInfo structures.

Discussion

A palette structure contains a header and a collection of color information structures, one for each color in the palette.

Availability
Declared In
Palettes.h

Constants

Usage Constants

Constants used to determine how the Palette Manager uses a specific palette color.

enum {
   pmCourteous = 0,
   pmDithered = 0x0001,
   pmTolerant = 0x0002,
   pmAnimated = 0x0004,
   pmExplicit = 0x0008,
   pmWhite = 0x0010,
   pmBlack = 0x0020,
   pmInhibitG2 = 0x0100,
   pmInhibitC2 = 0x0200,
   pmInhibitG4 = 0x0400,
   pmInhibitC4 = 0x0800,
   pmInhibitG8 = 0x1000,
   pmInhibitC8 = 0x2000
};
Constants
pmCourteous

The color accepts whatever value the Color Manager determines to be the closest match currently available in the device color table.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmDithered

[description forthcoming]

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmTolerant

The color accepts the Color Manager's choices on an indexed device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmAnimated

The color is used for special color animation effects.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmExplicit

The color specifies an index value rather than an RGB color and always generates the corresponding entry from the device's color table.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmWhite

Assign color to white on a 1-bit device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmBlack

Assign color to black on a 1-bit device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmInhibitG2

Inhibit on 2-bit grayscale device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmInhibitC2

Inhibit on 2-bit color device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmInhibitG4

Inhibit on 4-bit grayscale device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmInhibitC4

Inhibit on 4-bit color device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmInhibitG8

Inhibit on 8-bit grayscale device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmInhibitC8

Inhibit on 8-bit color device.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

Discussion

You can logically AND these constants in certain combinations to specify the value of ciUsage in a ColorInfo record.

The inhibit constants are used to indicate that a graphics device should be prevented from displaying the color at specified pixel depths. They are always used in combination with other usage constants.

Update Constants

Constants used to determine whether a window is updated based on various changes to the color environment.

enum {
   pmNoUpdates = 0x8000,
   pmBkUpdates = 0xA000,
   pmFgUpdates = 0xC000,
   pmAllUpdates = 0xE000
};
Constants
pmNoUpdates

Do not update the window when its color environment changes.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmBkUpdates

Update the window only when it is not the active window.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmFgUpdates

Update the window only when it is the active window.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

pmAllUpdates

Update the window whenever its color environment changes.

Available in Mac OS X v10.0 and later.

Declared in Palettes.h.

Discussion

You use these constants in the nCUpdates parameter of the NSetPalette function and the updates parameter of the SetPaletteUpdates function.


Last updated: 2006-07-13

Did this document help you? Yes It's good, but... Not helpful...