Technical Note TN2008

The CGDirectPalette API

CONTENTS Definitions Creating and Releasing Palettes Accessing Palette Information Copying Palettes Comparing Palettes Summary Downloadables

This Technote provides a reference for the CGDirectPalette API on Mac OS X. The CGDirectPalette API is designed to provide easy access to display palettes with the help of the CGDirectDisplay API. This Technote describes the important data types and all of the function calls in the API. A separate Technote covers the API provided by CGDirectDisplay.  Updated: [Nov 08 2000]

Definitions

Types used by the CGDirectPalette API:

Back to top

Creating and Releasing Palettes

CGDirectPaletteRef CGPaletteCreateDefaultColorPalette(void);

• Creates a new palette object representing the default 8 bit color palette.
• Release the resulting palette using CGPaletteRelease().

CGDirectPaletteRef CGPaletteCreateWithDisplay(
    CGDirectDisplayID display);

• Creates a copy of the specified display's current palette, if any.
• Returns NULL if the current display mode does not support a palette.
• Release the resulting palette using CGPaletteRelease().

CGDirectPaletteRef CGPaletteCreateWithCapacity(
    CGTableCount capacity );

• Creates a new palette object with the specified capacity.
• Initializes the entries from the default color palette.
• Release the resulting palette using CGPaletteRelease().

CGDirectPaletteRef CGPaletteCreateWithSamples(
    CGDeviceColor * sampleTable,
    CGTableCount sampleCount);

• Creates a new palette object with the specified capacity and contents.
• Release the resulting palette using CGPaletteRelease().

CGDirectPaletteRef CGPaletteCreateWithByteSamples(
    CGDeviceByteColor * sampleTable,
    CGTableCount sampleCount);

• Creates a new palette object with the specified capacity and contents.
• Identical to CGPaletteCreateWithSamples except it takes CGDeviceByteColors instead of CGDeviceColors.
• Release the resulting palette using CGPaletteRelease().

void CGPaletteRelease(
    CGDirectPaletteRef palette );

• Releases the palette.

Back to top

Accessing Palette Information

CGDeviceColor CGPaletteGetColorAtIndex(
    CGDirectPaletteRef palette,
    CGTableCount index);

• Returns the CGDeviceColor at the specified index.
• Returns black ( 0, 0, 0 ) if the index is out of range.

CGTableCount CGPaletteGetIndexForColor(
    CGDirectPaletteRef palette,
    CGDeviceColor color);

• Returns the index that most closely matches the specified color value.
• The index returned is for the palette color with the lowest root-mean-squared (RMS) error with repect to the specified color.

CGTableCount CGPaletteGetNumberOfSamples(
    CGDirectPaletteRef palette);

• Returns the number of samples in the palette.
• Returns 0 for an invalid CGDirectPaletteRef.

void CGPaletteSetColorAtIndex(
    CGDirectPaletteRef palette,
    CGDeviceColor color,
    CGTableCount index);

• Sets the color value at the specified index.
• Fails if the index is out of range.

Back to top

Copying Palettes

CGDirectPaletteRef CGPaletteCreateCopy(
    CGDirectPaletteRef palette);

• Creates a new palette object with the same capacity and contents as the specified palette.
• Release the resulting palette using CGPaletteRelease().

CGDirectPaletteRef CGPaletteCreateFromPaletteBlendedWithColor(
    CGDirectPaletteRef palette,
    CGPaletteBlendFraction fraction,
    CGDeviceColor color);

• Creates a new palette object by blending the specified palette with a fraction of the device color.
• Release the resulting palette using CGPaletteRelease().

Back to top

Comparing Palettes

Boolean CGPaletteIsEqualToPalette(
    CGDirectPaletteRef palette1,
    CGDirectPaletteRef palette2);

• Returns TRUE if the two palettes have the same capacity and contents.
• Returns FALSE otherwise.
• Returns FALSE if either or both CGDirectPaletteRefs are invalid.

Back to top

Summary

This Technote covers the basic information you need to start using the CGDirectPalette API, including the important type definitions and function calls. Information on using the CGDirectDisplay API is contained in a separate Technote.

Back to top

Downloadables

Back to top