---

CGColor Reference

Overview

The CGColorRef opaque type contains a set of components (such as red, green, and blue) that uniquely define a color, and a color space that specifies how those components should be interpreted. Quartz color objects provide a fast and convenient way to manage and set colors, especially colors that are used repeatedly. Quartz drawing operations use color objects for setting fill and stroke colors, managing alpha, and setting color with a pattern.

See also these related references: CGContext Reference, CGColorSpace Reference, and CGPattern Reference.

Functions by Task

Getting a Constant Color

• CGColorGetConstantColor

Retaining and Releasing Color Objects

• CGColorRelease
• CGColorRetain

Creating Quartz Colors

• CGColorCreate
• CGColorCreateCopy
• CGColorCreateGenericGray
• CGColorCreateGenericRGB
• CGColorCreateGenericCMYK
• CGColorCreateCopyWithAlpha
• CGColorCreateWithPattern

Getting Information about Quartz Colors

• CGColorEqualToColor
• CGColorGetAlpha
• CGColorGetColorSpace
• CGColorGetComponents
• CGColorGetNumberOfComponents
• CGColorGetPattern
• CGColorGetTypeID

Functions

CGColorCreate

Creates a Quartz color using a list of intensity values (including alpha) and an associated color space.

CGColorRef CGColorCreate (
   CGColorSpaceRef colorspace,
   const CGFloat components[]
);

Parameters

colorspace

A color space for the new color. Quartz retains this object; upon return, you may safely release it.

components

An array of intensity values describing the color. The array should contain n+1 values that correspond to the n color components in the specified color space, followed by the alpha component. Each component value should be in the range appropriate for the color space. Values outside this range will be clamped to the nearest correct value.

Return Value

A new Quartz color. You are responsible for releasing this object using CGColorRelease.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorCreateCopy

Creates a copy of an existing Quartz color.

CGColorRef CGColorCreateCopy (
   CGColorRef color
);

Parameters

color

A Quartz color.

Return Value

A copy of the specified color. You are responsible for releasing this object using CGColorRelease.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorCreateCopyWithAlpha

Creates a copy of an existing Quartz color, substituting a new alpha value.

CGColorRef CGColorCreateCopyWithAlpha (
   CGColorRef color,
   CGFloat alpha
);

Parameters

color

The Quartz color to copy.

alpha

A value that specifies the desired opacity of the copy. Values outside the range [0,1] are clamped to 0 or 1.

Return Value

A copy of the specified color, using the specified alpha value. You are responsible for releasing this object using CGColorRelease.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorCreateGenericCMYK

Creates a color in the Generic CMYK color space.

CGColorRef CGColorCreateGenericCMYK(
   CGFloat cyan,
   CGFloat magenta,
   CGFloat yellow,
   CGFloat black,
   CGFloat alpha
);

Parameters

cyan

A cyan value (0.0 - 1.0).

magenta

A magenta value (0.0 - 1.0).

yellow

A yellow value (0.0 - 1.0).

black

A black value (0.0 - 1.0).

alpha

An alpha value (0.0 - 1.0).

Return Value

A color object.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CGColor.h

CGColorCreateGenericGray

Creates a color in the Generic gray color space.

CGColorRef CGColorCreateGenericGray(
   CGFloat gray,
   CGFloat alpha
);

Parameters

gray

A grayscale value (0.0 - 1.0).

alpha

An alpha value (0.0 - 1.0).

Return Value

A color object.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CGColor.h

CGColorCreateGenericRGB

Creates a color in the Generic RGB color space.

CGColorRef CGColorCreateGenericRGB(
   CGFloat red,
   CGFloat green,
   CGFloat blue,
   CGFloat alpha
);

Parameters

red

A red component value (0.0 - 1.0).

green

A green component value (0.0 - 1.0).

blue

A blue component value (0.0 - 1.0).

alpha

An alpha value (0.0 - 1.0).

Return Value

A color object.

Availability

• Available in Mac OS X v10.5 and later.

Related Sample Code

• CALayerEssentials

Declared In

CGColor.h

CGColorCreateWithPattern

Creates a Quartz color using a list of intensity values (including alpha), a pattern color space, and a pattern.

CGColorRef CGColorCreateWithPattern (
   CGColorSpaceRef colorspace,
   CGPatternRef pattern,
   const CGFloat components[]
);

Parameters

colorspace

A pattern color space for the new color. Quartz retains the color space you pass in. On return, you may safely release it.

pattern

A pattern for the new color object. Quartz retains the pattern you pass in. On return, you may safely release it.

components

An array of intensity values describing the color. The array should contain n + 1 values that correspond to the n color components in the specified color space, followed by the alpha component. Each component value should be in the range appropriate for the color space. Values outside this range will be clamped to the nearest correct value.

Return Value

A new Quartz color. You are responsible for releasing this object using CGColorRelease.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorEqualToColor

Indicates whether two colors are equal.

bool CGColorEqualToColor (
   CGColorRef color1,
   CGColorRef color2
);

Parameters

color1

The first Quartz color to compare.

color2

The second Quartz color to compare.

Return Value

A Boolean value that, if true, indicates that the specified colors are equal. If the colors are not equal, the value is false.

Discussion

Two colors are equal if they have equal color spaces and numerically equal color components.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorGetAlpha

Returns the value of the alpha component associated with a Quartz color.

CGFloat CGColorGetAlpha (
   CGColorRef color
);

Parameters

color

A Quartz color.

Return Value

An alpha intensity value in the range [0,1]. The value represents the opacity of the color.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorGetColorSpace

Returns the color space associated with a Quartz color.

CGColorSpaceRef CGColorGetColorSpace (
   CGColorRef color
);

Parameters

color

A Quartz color.

Return Value

The Quartz color space for the specified color. You are responsible for retaining and releasing it as needed.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorGetComponents

Returns the values of the color components (including alpha) associated with a Quartz color.

const CGFloat * CGColorGetComponents (
   CGColorRef color
);

Parameters

color

A Quartz color.

Return Value

An array of intensity values for the color components (including alpha) associated with the specified color. The size of the array is one more than the number of components of the color space for the color.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorGetConstantColor

Returns a color object that represents a constant color.

CGColorRef CGColorGetConstantColor(
   CFStringRef colorName
);

Parameters

colorName

A color name. You can pass any of the “Constant Colors” constant.

Return Value

A color object.

Discussion

As CGColorGetConstantColor is not a “Copy” or “Create” function, it does not necessarily return a new reference each time it's called. As a consequence, you should not release the returned value. However, colors returned from CGColorGetConstantColor can be retained and released in a properly nested fashion, just as any other Core Foundation type can.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

CGColor.h

CGColorGetNumberOfComponents

Returns the number of color components (including alpha) associated with a Quartz color.

size_t CGColorGetNumberOfComponents (
   CGColorRef color
);

Parameters

color

A Quartz color.

Return Value

The number of color components (including alpha) associated with the specified color. This number is one more than the number of components of the color space for the color.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorGetPattern

Returns the pattern associated with a Quartz color in a pattern color space.

CGPatternRef CGColorGetPattern (
   CGColorRef color
);

Parameters

color

A Quartz color.

Return Value

The pattern for the specified color. You are responsible for retaining and releasing the pattern as needed.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorGetTypeID

Returns the Core Foundation type identifier for a Quartz color data type.

CFTypeID CGColorGetTypeID (
   void
);

Return Value

The Core Foundation type identifier for CGColorRef.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

CGColorRelease

Decrements the retain count of a Quartz color.

void CGColorRelease (
   CGColorRef color
);

Parameters

color

The Quartz color to release.

Discussion

This function is equivalent to CFRelease, except that it does not cause an error if the color parameter is NULL.

Availability

• Available in Mac OS X version 10.3 and later.

Related Sample Code

• CALayerEssentials

Declared In

CGColor.h

CGColorRetain

Increments the retain count of a Quartz color.

CGColorRef CGColorRetain (
   CGColorRef color
);

Parameters

color

The Quartz color to retain.

Return Value

The same color you passed in as the color parameter.

Discussion

This function is equivalent to CFRetain, except that it does not cause an error if the color parameter is NULL.

Availability

• Available in Mac OS X version 10.3 and later.

Declared In

CGColor.h

Data Types

CGColorRef

An opaque type that represents a color used in Quartz 2D drawing.

typedef struct CGColor *CGColorRef;

Discussion

CGColorRef is the fundamental data type used internally by Quartz to represent colors. CGColor objects. and the functions that operate on them, provide a fast and convenient way of managing and setting colors directly, especially colors that are reused (such as black for text).

In Mac OS X version 10.3 and later, CGColorRef is derived from CFTypeRef and inherits the properties that all Core Foundation types have in common. For more information, see CFType Reference.

Availability

• Available in Mac OS X v10.3 and later.

Declared In

CGColor.h

Constants

Constant Colors

Commonly used colors.

const CFStringRef kCGColorWhite;
const CFStringRef kCGColorBlack;
const CFStringRef kCGColorClear;

Constants

kCGColorWhite

The white color in the Generic gray color space.

Available in Mac OS X v10.5 and later.

Declared in CGColor.h.

kCGColorBlack

The black color in the Generic gray color space.

Available in Mac OS X v10.5 and later.

Declared in CGColor.h.

kCGColorClear

The clear color in the Generic gray color space.

Available in Mac OS X v10.5 and later.

Declared in CGColor.h.

Declared In

CGColor.h

---