Contact ADC

Next Page >

Hide TOC

Legacy Document

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	ImageCompression.k.h 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

Functions

SetDepth

Changes the pixel depth of a video device. (Deprecated. There is no replacement; 8-bit graphics mode is not supported by the Mac OS X GUI.)

OSErr SetDepth (
   GDHandle gd,
   short depth,
   short whichFlags,
   short flags
);

Parameters

gd: A handle to the GDevice structure of the video device whose pixel depth you wish to change.
depth: The mode ID returned by the HasDepth function indicating that the video device supports the desired pixel depth. Alternatively, you can pass the desired pixel depth directly in this parameter, although you should use the HasDepth function to ensure that the device supports this depth.
whichFlags: The gdDevType constant, which represents a bit in the gdFlags field of the GDevice structure. (If this bit is set to 0 in the GDevice structure, the video device is black and white; if the bit is set to 1, the device supports color.
flags: The value 0 or 1. If you pass 0 in this parameter, the SetDepth function changes the video device to black and white; if you pass 1 in this parameter, SetDepth changes the video device to color.

Return Value

Returns zero if successful, or it returns a nonzero value if it cannot impose the desired depth and display mode on the requested device.

Discussion

The SetDepth function does not change the 'scrn' resource; when the system is restarted, the original depth for this device is restored.

The Monitors control panel is the user interface for changing the pixel depth, color capabilities, and positions of video devices. Since the user can control the capabilities of the video device, your application should be flexible: although it may have a preferred pixel depth, your application should do its best to accommodate less than ideal conditions.

Use SetDepth only if your application can run on devices of a particular pixel depth and is unable to adapt to any other depth. Your application should display a dialog box that offers the user a choice between changing to that depth or canceling display of the image before your application uses SetDepth. Such a dialog box saves the user the trouble of going to the Monitors control panel before returning to your application.

Special Considerations

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.

Availability

Available in Mac OS X v10.0 and later.

Declared In

ImageCompression.k.h

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

Available in Mac OS X v10.0 and later.

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

Available in Mac OS X v10.0 and later.

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.

Next Page >

Hide TOC

Last updated: 2006-07-13

Did this document help you?
Yes: Tell us what works for you. It’s good, but: Report typos, inaccuracies, and so forth. It wasn’t helpful: Tell us what would have helped.




	Get information on Apple products. Visit the Apple Store online or at retail locations. 1-800-MY-APPLE Copyright © 2007 Apple Inc. All rights reserved. \| Terms of use \| Privacy Notice