CGShading Reference

Derived from
CFType
Framework
ApplicationServices/ApplicationServices.h
Companion guide
Quartz 2D Programming Guide
Declared in
CGShading.h

Overview

CGShadingRef is an opaque type used to define linear (axial) and radial gradient fills whose color transitions are controlled by a function (CGFunctionRef) that you provide. Shading means to fill using a smooth transition between colors across an area. To paint with a Quartz shading, you call CGContextDrawShading. This function fills the current clipping path using the specified color gradient, calling your parametric function repeatedly as it draws

An alternative to using a CGShading object is to use the CGGradientRef opaque type. For applications that run in OS X v10.5 and later, CGGradient objects are much simpler to use. (See CGGradient Reference.)

Functions by Task

Creating Shading Objects

Retaining and Releasing Shading Objects

Getting the CFType ID

Functions

CGShadingCreateAxial

Creates a shading object to use for axial shading.

CGShadingRef CGShadingCreateAxial (
   CGColorSpaceRef colorspace,
   CGPoint start,
   CGPoint end,
   CGFunctionRef function,
   bool extendStart,
   bool extendEnd
);
Parameters
colorspace

The color space in which color values are expressed. Quartz retains this object; upon return, you may safely release it.

start

The starting point of the axis, in the shading's target coordinate space.

end

The ending point of the axis, in the shading's target coordinate space.

function

A CGFunction object created by the function CGFunctionCreate. This object refers to your function for creating an axial shading. Quartz retains this object; upon return, you may safely release it.

extendStart

A Boolean value that specifies whether to extend the shading beyond the starting point of the axis.

extendEnd

A Boolean value that specifies whether to extend the shading beyond the ending point of the axis.

Return Value

A new Quartz axial shading. You are responsible for releasing this object using CGShadingRelease.

Discussion

An axial shading is a color blend that varies along a linear axis between two endpoints and extends indefinitely perpendicular to that axis. When you are ready to draw the shading, call the function CGContextDrawShading.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGShading.h

CGShadingCreateRadial

Creates a shading object to use for radial shading.

CGShadingRef CGShadingCreateRadial (
   CGColorSpaceRef colorspace,
   CGPoint start,
   CGFloat startRadius,
   CGPoint end,
   CGFloat endRadius,
   CGFunctionRef function,
   bool extendStart,
   bool extendEnd
);
Parameters
colorspace

The color space in which color values are expressed. Quartz retains this object; upon return, you may safely release it.

start

The center of the starting circle, in the shading's target coordinate space.

startRadius

The radius of the starting circle, in the shading's target coordinate space.

end

The center of the ending circle, in the shading's target coordinate space.

endRadius

The radius of the ending circle, in the shading's target coordinate space.

function

A CGFunction object created by the function CGFunctionCreate. This object refers to your function for creating a radial shading. Quartz retains this object; upon return, you may safely release it.

extendStart

A Boolean value that specifies whether to extend the shading beyond the starting circle.

extendEnd

A Boolean value that specifies whether to extend the shading beyond the ending circle.

Return Value

A new Quartz radial shading. You are responsible for releasing this object using CGShadingRelease.

Discussion

A radial shading is a color blend that varies between two circles. To draw the shading, call the function CGContextDrawShading.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGShading.h

CGShadingGetTypeID

Returns the Core Foundation type identifier for Quartz shading objects.

CFTypeID CGShadingGetTypeID (
   void
);
Return Value

The Core Foundation identifier for the opaque type CGShadingRef.

Availability
  • Available in iOS 2.0 and later.
Declared In
CGShading.h

CGShadingRelease

Decrements the retain count of a shading object.

void CGShadingRelease (
   CGShadingRef shading
);
Parameters
shading

The shading object to release.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Declared In
CGShading.h

CGShadingRetain

Increments the retain count of a shading object.

CGShadingRef CGShadingRetain (
   CGShadingRef shading
);
Parameters
shading

The shading object to retain.

Return Value

The same shading object you passed in as the shading parameter.

Discussion

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

Availability
  • Available in iOS 2.0 and later.
Declared In
CGShading.h

Data Types

CGShadingRef

An opaque type that represents a Quartz shading.

typedef struct CGShading *CGShadingRef;
Availability
  • Available in iOS 2.0 and later.
Declared In
CGShading.h


© 2003, 2006 Apple Computer, Inc. All Rights Reserved. (Last updated: 2006-12-22)

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