---

A Comparison of CGShading and CGGradient Objects

With two type of objects available for creating gradients, you might be wondering which one is best to use. This section helps answer that question.

The CGShadingRef opaque data type gives you control over how the color at each point in the gradient is computed. Before you can create a CGShading object, you must create a CGFunction object (CGFunctionRef) that defines a function for computing colors in the gradient. Writing a custom function gives you the freedom to create smooth gradients, such as those shown in Figure 8-1, Figure 8-3, and Figure 8-5 or more unconventional effects, such as that shown in Figure 8-12.

When you create a CGShading object, you specify whether it is axial (linear) or radial. Along with the gradient calculation function (encapsulated as a CGFunction object) you also supply a colorspace, and starting and ending points or radii, depending on whether you draw an axial or radial gradient. At drawing time, you simply pass the CGShading object along with the drawing context to the function CGContextDrawShading. Quartz invokes your gradient calculation function for each point in the gradient.

A CGGradient object is a subset of a CGShading object that’s designed with ease-of-use in mind. The CGGradientRef opaque data type is straightforward to use because Quartz calculates the color at each point in the gradient for you—you don’t supply a gradient calculation function. When you create a gradient object, you provide an array of locations and colors. Quartz calculates a gradient for each set of contiguous locations, using the color you assign to each location as the end points for the gradient. You can set a gradient object to use a single starting and ending location, as shown in Figure 8-1, or you can provide a number of points to create an effect similar to what’s shown in Figure 8-2. The ability to provide more than two locations is an advantage over using a CGShading object, which is limited to two locations.

When you create a CGGradient object, you simply set up a colorspace, locations, and a color for each location. When you draw to a context using a gradient object, you specify whether Quartz should draw an axial or radial gradient. At drawing time, you specify starting and ending points or radii, depending on whether you draw an axial or radial gradient. This contrasts with CGShading objects, whose geometry is defined at creation time, not at drawing time.

A major factor is deciding which opaque type to use is the minimum system that your application runs on. The CGShadingRef opaque data type was introduced in Mac OS X v10.2. The CGGradientRef opaque data type is available starting in Mac OS X v10.5. If your code must run on versions of Mac OS X earlier than v10.5, you’ll need to draw gradients using a CGShading object. If your code is designed for Mac OS X v10.5 and later, you can use either opaque type. Table 8-1 summarizes the differences between the two opaque data types.

---