CGColorSpace Reference

Overview

The CGColorSpaceRef opaque type encapsulates color space information that is used to specify how Quartz interprets color information. A color space specifies how color values are interpreted. A color space is multi-dimensional, and each dimension represents a specific color component. For example, the colors in an RGB color space have three dimensions or components—red, green, and blue. The intensity of each component is represented by floating point values—their range and meaning depends on the color space in question.

Different types of devices (scanners, monitors, printers) operate within different color spaces (RGB, CMYK, grayscale). Additionally, two devices of the same type (for example, color displays from different manufacturers) may operate within the same kind of color space, yet still produce a different range of colors, or gamut. Color spaces that are correctly specified ensure that an image has a consistent appearance regardless of the output device.

Quartz supports several kinds of color spaces:

• Calibrated color spaces ensure that colors appear the same when displayed on different devices. The visual appearance of the color is preserved, as far as the capabilities of the device allow.

• Device-dependent color spaces are tied to the system of color representation of a particular device. Device color spaces are not recommended when high-fidelity color preservation is important.

• Special color spaces—indexed and pattern. An indexed color space contains a color table with up to 256 entries and a base color space to which the color table entries are mapped. Each entry in the color table specifies one color in the base color space. A pattern color space is used when stroking or filling with a pattern. Pattern color spaces are supported in OS X version 10.1 and later.

Functions by Task

Creating Device-Independent Color Spaces

• CGColorSpaceCreateCalibratedGray
• CGColorSpaceCreateCalibratedRGB
• CGColorSpaceCreateICCBased
• CGColorSpaceCreateWithICCProfile
• CGColorSpaceCreateLab

Creating Generic or Device-Dependent Color Spaces

In OS X v10.4 and later, the color space returned by each of these functions is no longer device-dependent and is replaced by a generic counterpart.

• CGColorSpaceCreateDeviceCMYK
• CGColorSpaceCreateDeviceGray
• CGColorSpaceCreateDeviceRGB

Creating Special Color Spaces

• CGColorSpaceCreateIndexed
• CGColorSpaceCreatePattern
• CGColorSpaceCreateWithName

Getting Information About Color Spaces

• CGColorSpaceGetNumberOfComponents
• CGColorSpaceGetTypeID
• CGColorSpaceGetModel
• CGColorSpaceGetBaseColorSpace
• CGColorSpaceGetColorTableCount
• CGColorSpaceGetColorTable

Retaining and Releasing Color Spaces

• CGColorSpaceRelease
• CGColorSpaceRetain

Functions

CGColorSpaceCreateCalibratedGray

Creates a calibrated grayscale color space.

CGColorSpaceRef CGColorSpaceCreateCalibratedGray(
   const CGFloat whitePoint[3],
   const CGFloat blackPoint[3],
   CGFloat gamma
);

CGColorSpaceCreateCalibratedRGB

Creates a calibrated RGB color space.

CGColorSpaceRef CGColorSpaceCreateCalibratedRGB(
   const CGFloat whitePoint[3],
   const CGFloat blackPoint[3],
   const CGFloat gamma[3],
   const CGFloat matrix[9]
);

CGColorSpaceCreateDeviceCMYK

Creates a device-dependent CMYK color space.

CGColorSpaceRef CGColorSpaceCreateDeviceCMYK(
   void
);

CGColorSpaceCreateDeviceGray

Creates a device-dependent grayscale color space.

CGColorSpaceRef CGColorSpaceCreateDeviceGray(
   void
);

CGColorSpaceCreateDeviceRGB

Creates a device-dependent RGB color space.

CGColorSpaceRef CGColorSpaceCreateDeviceRGB(
   void
);

CGColorSpaceCreateICCBased

Creates a device-independent color space that is defined according to the ICC color profile specification.

CGColorSpaceRef CGColorSpaceCreateICCBased(
   size_t nComponents,
   const CGFloat *range,
   CGDataProviderRef profile,
   CGColorSpaceRef alternate
);

CGColorSpaceCreateIndexed

Creates an indexed color space, consisting of colors specified by a color lookup table.

CGColorSpaceRef CGColorSpaceCreateIndexed(
   CGColorSpaceRef baseSpace,
   size_t lastIndex,
   const unsigned char *colorTable
);

CGColorSpaceCreateLab

Creates a device-independent color space that is relative to human color perception, according to the CIE L*a*b* standard.

CGColorSpaceRef CGColorSpaceCreateLab(
   const CGFloat whitePoint[3],
   const CGFloat blackPoint[3],
   const CGFloat range[4]
);

CGColorSpaceCreatePattern

Creates a pattern color space.

CGColorSpaceRef CGColorSpaceCreatePattern(
   CGColorSpaceRef baseSpace
);

CGColorSpaceCreateWithICCProfile

Creates an ICC-based color space using the ICC profile contained in the specified data.

CGColorSpaceRef CGColorSpaceCreateWithICCProfile(
   CFDataRef data
);

CGColorSpaceCreateWithName

Creates a specified type of Quartz color space.

CGColorSpaceRef CGColorSpaceCreateWithName(
   CFStringRef name
);

CGColorSpaceGetBaseColorSpace

Returns the base color space of a pattern or indexed color space.

CGColorSpace CGColorSpaceGetBaseColorSpace(
   CGColorSpaceRef space
);

CGColorSpaceGetColorTable

Copies the entries in the color table of an indexed color space.

void CGColorSpaceGetColorTable(
   CGColorSpaceRef space,
   uint8_t *table);
);

CGColorSpaceGetColorTableCount

Returns the number of entries in the color table of an indexed color space.

size_t CGColorSpaceGetColorTableCount(
   CGColorSpaceRef space
);

CGColorSpaceGetModel

Returns the color space model of the provided color space.

CGColorSpaceModel CGColorSpaceGetModel(
   CGColorSpaceRef space
);

CGColorSpaceGetNumberOfComponents

Returns the number of color components in a color space.

size_t CGColorSpaceGetNumberOfComponents(
   CGColorSpaceRef cs
);

CGColorSpaceGetTypeID

Returns the Core Foundation type identifier for Quartz color spaces.

CFTypeID CGColorSpaceGetTypeID(
   void
);

CGColorSpaceRelease

Decrements the retain count of a color space.

void CGColorSpaceRelease(
   CGColorSpaceRef cs
);

CGColorSpaceRetain

Increments the retain count of a color space.

CGColorSpaceRef CGColorSpaceRetain(
   CGColorSpaceRef cs
);

Data Types

CGColorSpaceRef

An opaque type that encapsulates color space information.

typedef struct CGColorSpace *CGColorSpaceRef;

Constants

Color Space Models

Models for color spaces.

enum CGColorSpaceModel {
   kCGColorSpaceModelUnknown = -1,
   kCGColorSpaceModelMonochrome,
   kCGColorSpaceModelRGB,
   kCGColorSpaceModelCMYK,
   kCGColorSpaceModelLab,
   kCGColorSpaceModelDeviceN,
   kCGColorSpaceModelIndexed,
   kCGColorSpaceModelPattern
};
typedef int32_t CGColorSpaceModel;

Constants

kCGColorSpaceModelUnknown

An unknown color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelMonochrome

A monochrome color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelRGB

An RGB color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelCMYK

A CMYK color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelLab

A Lab color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelDeviceN

A DeviceN color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelIndexed

An indexed color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGColorSpaceModelPattern

A pattern color space model.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

Color Rendering Intents

Handling options for colors that are not located within the destination color space of a graphics context.

enum CGColorRenderingIntent {
   kCGRenderingIntentDefault,
   kCGRenderingIntentAbsoluteColorimetric,
   kCGRenderingIntentRelativeColorimetric,
   kCGRenderingIntentPerceptual,
   kCGRenderingIntentSaturation
};
typedef enum CGColorRenderingIntent CGColorRenderingIntent;

Constants

kCGRenderingIntentDefault

The default rendering intent for the graphics context.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGRenderingIntentAbsoluteColorimetric

Map colors outside of the gamut of the output device to the closest possible match inside the gamut of the output device. This can produce a clipping effect, where two different color values in the gamut of the graphics context are mapped to the same color value in the output device’s gamut. Unlike the relative colorimetric, absolute colorimetric does not modify colors inside the gamut of the output device.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGRenderingIntentRelativeColorimetric

Map colors outside of the gamut of the output device to the closest possible match inside the gamut of the output device. This can produce a clipping effect, where two different color values in the gamut of the graphics context are mapped to the same color value in the output device’s gamut. The relative colorimetric shifts all colors (including those within the gamut) to account for the difference between the white point of the graphics context and the white point of the output device.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGRenderingIntentPerceptual

Preserve the visual relationship between colors by compressing the gamut of the graphics context to fit inside the gamut of the output device. Perceptual intent is good for photographs and other complex, detailed images.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.

kCGRenderingIntentSaturation

Preserve the relative saturation value of the colors when converting into the gamut of the output device. The result is an image with bright, saturated colors. Saturation intent is good for reproducing images with low detail, such as presentation charts and graphs.

Available in iOS 2.0 and later.

Declared in CGColorSpace.h.