Volume Number: 21 (2005)
Issue Number: 8
Column Tag: Programming

Mac OS X Programming

Mineralogy 101: Use the Quartz (2D), Luke!

by David Hill

Welcome!

While most of you have probably heard of Mac OS X's 2D drawing API, Quartz 2D, how many of you have taken the time to pull up the headers and get your hands dirty figuring out what it can do? For those of you that haven't, whether you've been too busy or just too intimidated to learn another drawing API, I'm going to walk you through some of the basics in this article. I'm not going to dwell on theory or the details of the drawing model. Instead, we're just going to play with the API and perhaps learn something along the way. I'll present short snippets of drawing code that you can drop into a sample project and try out. Feel free to play with the code and experiment on your own.

I'm basing the code on Mac OS X 10.3 (Panther) and Xcode 1.5 so if you're running a different version of the OS or Xcode, you'll need to adjust the content accordingly. In particular, watch out for functions that are only available in Panther. The Quartz 2D headers very specifically mark those APIs that are only available in 10.3 and later with the flag AVAILABLE_MAC_OS_X_VERSION_10_3_AND_LATER. In addition, while I'm providing a Cocoa project with this article, the Quartz 2D code is clearly marked and valid for Carbon as well as Cocoa. Carbon developers should watch out for differences between the coordinate systems, however, since Cocoa and Quartz 2D place the origin in the bottom left corner with +y pointing up while Carbon (older QuickDraw code as well as Carbon Events) assumes that the origin is in the upper left corner with +y pointing down.

One final note about Quartz 2D: the headers, functions, and types are all prefixed with CG as an abbreviation for Quartz 2D's older name, Core Graphics. Luckily, Xcode knows how to find the headers when you need to take a look. Just hit CMD-D, type the name of the header you're looking for ("CGContext.h", for example), and hit return. You can also CMD-double-click on a Quartz 2D type or function name in your code and Xcode will find the header for you.

The Quartz2DShell Project

Those of you following along at home will need a simple project to hold the Quartz 2D code snippets we'll be talking about. Either download the sample code for this article or start up Xcode and create a new Cocoa application project (for simplicity, I'm not using the Cocoa Document-based project). I've called mine Quartz2DShell but feel free to be more creative. Once Xcode has created the project, double click on the MainMenu.nib to open it in Interface Builder. Switch over to the Classes tab in the MainMenu.nib window, search for NSView, click on NSView in the class list, and select Subclass NSView from the Classes menu. IB should select the new NSView subclass (give it a suitable name like Quartz2DView). Then, select Create Files from the Classes menu and you're almost done. Add a Custom View to the window, resize it to fill the window, and set the resizing springs so that the view tracks the window. Finally, set the view's custom class to Quartz2DView and you're done. Save the nib file and return to Xcode. You should see Quartz2DView.h and Quartz2DView.m waiting for you.

Getting Started

The first thing you need in order to draw with Quartz 2D is a CGContextRef. For those of you familiar with other drawing APIs, you can think of a CGContextRef as a QuickDraw port or a GDI device context. CGContextRefs hold your drawing state and give you a place to draw. There are several different ways to obtain a CGContextRef but for our purposes we'll simply retrieve one from our custom view by replacing the existing drawRect: method with the code shown below.

	- (void)drawRect:(NSRect)rect
   {
      // get the current CGContextRef for the view
      CGContextRef currentContext =
         (CGContextRef)[[NSGraphicsContext currentContext]
         graphicsPort];

      // grab some useful view size numbers
      NSRect bounds = [self bounds];
      float width = NSWidth( bounds );
      float height = NSHeight( bounds );
      float originX = NSMinX( bounds );
      float originY = NSMinY( bounds );
      float maxX = NSMaxX( bounds );
      float maxY = NSMaxY( bounds );
      float middleX = NSMidX( bounds );
      float middleY = NSMidY( bounds );

      ////
      ////   insert the Quartz 2D drawing code snippets here
      ////

      CGContextFlush( currentContext );
   }

Carbon developers working with WindowRefs will need to get the port for the window and then call QDBeginCGContext() to obtain the appropriate CGContextRef. Note that you'll also need to call CGContextFlush() and then QDEndCGContext() once you're done drawing. Your function drawing code should look something like this:

   CGrafPtr portPtr = GetWindowPort( windowRef );
   CGContextRef currentContext = NULL;
   QDBeginCGContext( portPtr, ¤tContext );

   // insert the Quartz 2D drawing code snippets here

   CGContextFlush( currentContext );	
   // update the window
   QDEndCGContext( portPtr, ¤tContext );

Rectangles

As I mentioned earlier, the coordinate system of the CGContextRef has the origin in the bottom left corner and the +y axis points up. What I didn't tell you was that the context is also set up such that one context unit is equivalent to one view pixel. As we'll see a little later, Quartz 2D has a very flexible coordinate transformation system based on the concept of the Current Transformation Matrix (CTM) and so you can change that one-to-one mapping if you like. For now, we'll leave well enough alone and keep things simple. As long as we don't change the CTM, we can use coordinates that match the dimensions of the view and get the results we'd expect.

Let's start with some really basic drawing. Most of the Quartz 2D API is based on the concept of a path (we'll talk about paths in just a minute) but there is a really straightforward convenience function for drawing rectangles called CGContextFillRect(). CGContextFillRect() takes the CGContextRef you're drawing into and the rectangle you'd like Quartz 2D to fill. Insert the following code into the drawRect: method and then build and run the app.

   //   try a simple rectangle with the convenience function CGContextFillRect
      CGRect testRect =
         CGRectMake(   originX + width / 4.0,	
   // left
                           originY + height / 4.0,
   // bottom
                           width / 2.0,						
   // width
                           height / 2.0 );				
   // height
      CGContextFillRect( currentContext, testRect );

You should see a large black rectangle in the middle of your window (Figure 1). Since we're basing our rectangle on the dimensions of the custom view, if you set up the resizing springs correctly in IB you should be able to resize the window and have the rectangle adjust accordingly in real time.

Now that you've drawn your first Quartz 2D graphic, let's move on to a slightly more complicated topic. As I mentioned before, Quartz 2D likes to deal in paths. In fact, the CGContextFillRect() function really just creates, fills, and destroys a rectangular path under the hood. Let's take a look at what the CGContextFillRect() function is doing for us. Drop this code into the drawRect: code in place of the previous snippet:

      CGContextBeginPath( currentContext );
      CGContextMoveToPoint( currentContext,
         originX + width / 4.0, originY + height / 4.0 );
      CGContextAddLineToPoint( currentContext,
         originX + width / 4.0 + width / 2.0,
         originY + height / 4.0 );
      CGContextAddLineToPoint( currentContext,
         originX + width / 4.0 + width / 2.0,
         originY + height / 4.0 + height / 2.0 );
      CGContextAddLineToPoint( currentContext,
         originX + width / 4.0,
         originY + height / 4.0 + height / 2.0 );
      CGContextFillPath( currentContext );

Here, we're starting a new path with CGContextBeginPath(), moving to the bottom left corner of the rectangle, adding lines along the bottom, right, and top edges, and then filling the path with CGContextFillPath(). Note that we didn't have to add the fourth line to close the path ourselves. For the purposes of filling the path, Quartz 2D will automatically close the current path (if it is still open) with a straight line back to its starting point whenever we call one of the drawing functions.

One interesting thing to note about Quartz 2D and paths: drawing with the current path (either filling, stroking, or both) consumes that path. If we were to add another drawing call like CGContextStrokePath() after our call to CGContextFillPath(), nothing would happen. We would have to recreate our rectangular path in order to draw it again. Thankfully, since performing both a fill and a stroke (drawing the outline) of a path is so common, Quartz 2D provides a way to do both in one function call. Simply call CGContextDrawPath() and pass in kCGPathFillStroke or kCGPathEOFillStroke for the drawing mode parameter and Quartz 2D will fill and stroke the path in one operation.

In order for the stroke to be visible over the fill, I'll need to show you one more thing: colors. There are two important colors in Quartz 2D: the fill color and the stroke color. There are several ways to set colors but, for the purposes of this article, we'll stick with the simplest two: CGContextSetRGBFillColor() and CGContextSetRGBStrokeColor(). (If you want to investigate Quartz 2D's color support in more detail, check out CGColorRefs and CGColorSpaceRefs). Replace the call to CGContextFillPath() with these lines and watch what happens:

   // Set the red, green, blue, and alpha color values
   CGContextSetRGBFillColor( currentContext,
      1.0, 0.0, 0.0, 1.0 );
   CGContextSetRGBStrokeColor( currentContext,
      0.0, 1.0, 0.0, 1.0 );
   CGContextDrawPath( currentContext, kCGPathFillStroke );

Now your code should draw a red rectangle with a green outline. For those of you like me with poor eyesight, a bad monitor, or both, you may have some trouble seeing the single-pixel outline. Let's make the stroke wider and more obvious. Add this line before the call to CGContextDrawPath():

   CGContextSetLineWidth( currentContext, 10 );

Ah, now that the outline is more visible (Figure 2), you can clearly see why I said that Quartz 2D would close the path for the purposes of filling the path. Quartz 2D didn't automatically close the path for the stroke so the left edge of the rectangle doesn't have a green line. Close the path manually (Figure 3) by adding this call to CGContextClosePath() after the third CGContextAddLineToPoint() call:

 CGContextClosePath( currentContext );

Lines

Now that you've got a handle on rectangles, we'll move on to some of the fun things you can do with lines. We've already added lines to paths to make our rectangles and changed the line width but there are some other things we can tweak to control the way lines look. Replace your rectangle code with the line code below that explores the different line cap styles.

   // draw some wide lines with different endcaps and dashes
   CGContextSetLineWidth( currentContext, 15 );
		
   CGContextSetLineCap( currentContext, kCGLineCapButt );
   CGContextBeginPath( currentContext );
   CGContextMoveToPoint( currentContext,
      originX + 15, originY + 15 );
   CGContextAddLineToPoint( currentContext,
      maxX - 15, originY + 15 );
   CGContextStrokePath( currentContext );
	
   CGContextSetLineCap( currentContext, kCGLineCapRound );
   CGContextBeginPath( currentContext );
   CGContextMoveToPoint( currentContext,
      originX + 15, originY + 45 );
   CGContextAddLineToPoint( currentContext,
      maxX - 15, originY + 45 );
   CGContextStrokePath( currentContext );
	
   CGContextSetLineCap( currentContext, kCGLineCapSquare );
   CGContextBeginPath( currentContext );
   CGContextMoveToPoint( currentContext,
      originX + 15, originY + 75 );
   CGContextAddLineToPoint( currentContext,
      maxX - 15, originY + 75 );
   CGContextStrokePath( currentContext );

This code produces three fat lines (Figure 4) with different end styles: butt, round, and square. Feel free to increase the line size or zoom in (using Mac OS X's accessibility controls) to get a better look at the end caps. Also, notice that while the line with the kCGLineCapButt style ends right where the path starts and ends, the other two line cap styles cause the line to overflow the end points. This happens because the round and square cap styles draw a half-circle and a square, respectively, centered on the end point of the path whereas the butt cap style squares off the end of the path perpendicular to the path at the endpoint.

Quartz 2D can also join lines in three different ways: miter, round, and bevel. The following code draws three paths composed of two lines each (Figure 5). Notice the difference in the corners where the lines meet. Depending on the size of your window, the miter and bevel join styles may look the same. Narrow the window slowly and the mitered lines will eventually change as the angle between the lines increases (Figure 6). I don't know about you but I'm really glad Quartz 2D figures all of this out for me.

   // test the different line join styles
   CGContextSetLineWidth( currentContext, 15 );
   CGContextSetLineCap( currentContext, kCGLineCapButt );

   CGContextSetLineJoin( currentContext, kCGLineJoinMiter );
   CGContextBeginPath( currentContext );
   CGContextMoveToPoint( currentContext,
      originX + 15, originY + 105 );
   CGContextAddLineToPoint( currentContext,
      maxX - 75, originY + 105 );
   CGContextAddLineToPoint( currentContext,
      originX + 15, originY + 155 );
   CGContextStrokePath( currentContext );
	
   CGContextSetLineJoin( currentContext, kCGLineJoinRound );
   CGContextBeginPath( currentContext );
   CGContextMoveToPoint( currentContext,
      originX + 15, originY + 175 );
   CGContextAddLineToPoint( currentContext,
      maxX - 75, originY + 175 );
   CGContextAddLineToPoint( currentContext,
      originX + 15, originY + 225 );
   CGContextStrokePath( currentContext );
	
   CGContextSetLineJoin( currentContext, kCGLineJoinBevel );
   CGContextBeginPath( currentContext );
   CGContextMoveToPoint( currentContext,
      originX + 15, originY + 245 );
   CGContextAddLineToPoint( currentContext,
      maxX - 75, originY + 245 );
   CGContextAddLineToPoint( currentContext,
      originX + 15, originY + 295 );
   CGContextStrokePath( currentContext );

Paths

Up to this point, we've been drawing by setting up the current path in a context and then asking the context to draw that path. This works fine but it can be awkward when you want to reuse a path multiple times. Luckily, Quartz 2D includes a separate path object, CGPathRef, that you can create and reuse over and over again. The usage pattern is simple: create a mutable path, add to the path in much the same way as we did for the current path in the context, add the path to the context, and ask the context to draw. Note: the NULL parameters below are CGAffineTransforms that allow you to transform the points as they're added to the path. We won't worry about those in this article so we'll pass in NULL to keep Quartz 2D from doing any extra work. Drop in the code snippet below and try it out.

      //   create a path and use it
      path = CGPathCreateMutable();
      CGPathMoveToPoint( path, NULL,
         originX + 15, originY + 120 );
      CGPathAddLineToPoint( path, NULL,
         maxX - 75, originY + 120 );
      CGPathAddLineToPoint( path, NULL,
         originX + 15, originY + 170 );
      CGContextAddPath( currentContext, path );
      CGPathRelease( path );
      CGContextStrokePath( currentContext );

Not too exciting, is it? Have patience. We're getting to the good part. Creating a CGPathRef, adding to it, drawing with it, and then releasing it isn't terribly efficient. What you really want to do is create the path, set it up, and then use it multiple times before releasing it. Get rid of the boring path code above and replace it with this:

   CGContextSetLineWidth( currentContext, 2 );

   // create and set up the path starting at the origin
   path = CGPathCreateMutable();
   CGPathMoveToPoint( path, NULL, originX, originY );
   CGPathAddLineToPoint( path, NULL,
      originX + width / 8.0, originY );
   CGPathMoveToPoint( path, NULL,
      originX + width / 8.0, originY + 0.25 * width / 8.0 );
   CGPathAddLineToPoint( path, NULL,
      originX + 0.75 * width / 8.0,
      originY - 0.25 * width / 8.0 );

   // translate the origin to the middle of the window
   CGContextTranslateCTM( currentContext,
      middleX, middleY );
		
   // scale the context so that things are twice as big in both directions
   CGContextScaleCTM( currentContext, 2, 2 );
	
   float radiansToRotate = 2 * M_PI / 21;
   int i;
   for ( i = 0; i < 21; i++ )
   {
      // add the path to the context and draw
      CGContextAddPath( currentContext, path );
      CGContextStrokePath( currentContext );
			
      // rotate the context just a bit
      CGContextRotateCTM( currentContext, radiansToRotate );
   }

   // we're done with the path
   CGPathRelease( path );

This code adds some new twists (Figure 7) to what you've seen before by manipulating the CTM. Remember the CTM? I told you that as long as we didn't mess with it, we could draw using view coordinates and things would turn out like we'd expect. Well, now we've got to change the CTM or we won't be able to see that we're drawing the CGPathRef object multiple times. In this case, we set up the path, set up the CTM so that the coordinate system origin is in the middle of the window, make things a bit bigger, and then enter a loop. The loop draws the path object and then rotates the CTM a bit so that we don't draw the path over itself 21 times in a row. Note: CGContextRotateCTM() rotates the CTM such that the next path you draw appears to rotate counter-clockwise around the origin.

There's one last stop on our tour of paths and lines: dashes. Quartz 2D makes it almost too simple to draw beautiful dashed lines. All you need to do is set up an array containing the dash lengths you want, make a call to CGContextSetLineDash(), and stroke your paths. Quartz 2D takes care of the rest. Take this code for a spin (Figure 8) and see what you think.

   // play with line dashes
   CGContextSetLineWidth( currentContext, 10.0 );
   float dashPhase = 0.0;
   float dashLengths[] = { 20, 30, 40, 30, 20, 10 };
   CGContextSetLineDash( currentContext,
      dashPhase, dashLengths,
      sizeof( dashLengths ) / sizeof( float ) );
		
   CGContextMoveToPoint( currentContext,
      originX + 10, middleY );
   CGContextAddLineToPoint( currentContext,
      maxX - 10, middleY );
   CGContextStrokePath( currentContext );

Here, the dashLength[] array sets up dashes of length of 20, 40, and 20 with gaps in between of length 30, 30, and 10. You can also adjust the phase (where the dash pattern starts - play with it a bit) when you call CGContextSetLineDash().

Dashes work fine with straight, horizontal lines but that's boring. Let's try something more interesting. Here's another snippet that draws curves instead of lines (Figure 9). Add this code after the CGContextStrokePath():

   // play with curves & dashes
   CGContextSetRGBFillColor( currentContext,
      1.0, 0.0, 0.0, 1.0 );
   CGContextSetRGBStrokeColor( currentContext,
      0.0, 1.0, 0.0, 1.0 );
	
   CGContextMoveToPoint( currentContext, middleX, maxY );
   CGContextAddCurveToPoint( currentContext, originX, maxY,
      originX, 0.667 * maxY, middleX, middleY );
   CGContextAddCurveToPoint( currentContext,
      maxX, 0.333 * maxY, maxX, originY, middleX, originY );
   CGContextAddCurveToPoint( currentContext, originX,
      originY, originX, 0.333 * maxY, middleX, middleY );
   CGContextAddCurveToPoint( currentContext, maxX,
      0.667 * maxY, maxX, maxY, middleX, maxY );

   CGContextDrawPath( currentContext, kCGPathFillStroke );

Notice how the dash pattern moves along the curve as you resize the window while the pattern remains fixed on the horizontal line? That is because Quartz 2D starts the dash pattern at the beginning of the path and repeats the pattern as many times as necessary to reach the end of the path. If the length of the path changes, Quartz 2D just continues the pattern as necessary. Since we're always looking at the beginning of the path for the straight line, the pattern doesn't appear to shift. However, with the curve we can see a clear beginning and end of the path. That makes the additional dashes added and removed quite obvious as the curve length changes.

Shadows

Mac OS X has always provided very nice shadows under windows and other UI elements. With Panther, Apple added APIs to Quartz 2D to allow you to draw your own shadows. There are two shadow APIs: the simple one and the slightly less simple one. The former, CGContextSetShadow(), sets up a simple black shadow. The latter, CGContextSetShadowWithColor(), allows you to specify the color of the shadow. We'll use the black version here but knock yourself out with colored shadows if that's your thing. Add this line right after the "play with curves & dashes" comment.

 CGContextSetShadow( currentContext,
      CGSizeMake( 14.0, -14.0 ), 7.0 );

Now our curve has a nice soft shadow (Figure 10) but if you look closely you'll see that the dashed green outline is casting a shadow on the red filled portion. Depending on the look you're going for, that may or may not be what you want. It turns out that even though we're making a single call to fill and stroke the path, Quartz 2D is performing two separate operations and each result has a shadow. The fill comes first with the bottom shadow and then the stroke comes along and draws its shadow on top of the fill. So, if you want the combined result of the two operations to have a single shadow, what do you do? You'll need to use a transparency layer, yet another new feature added to Quartz 2D for Panther.

Transparency layers only require two function calls, one to begin the layer and one to end the layer. In between, all Quartz 2D drawing for the context goes into the layer instead of the destination of the context. Once you end the layer, all of the drawing in the layer is composited into the context using the shadow state of the context. It will make more sense if you try it out yourself. There are two lines of code below. Add the CGContextBeginTransparencyLayer() call right after the call to CGContextSetRGBStrokeColor() and the CGContextEndTransparencyLayer() call right after the CGContextDrawPath() call.

CGContextBeginTransparencyLayer( currentContext, NULL );
   CGContextEndTransparencyLayer( currentContext );

With that change, you should see your green-outlined, red-filled figure-eight with a single shadow behind the whole thing (Figure 11). Oh, and you're probably still drawing the black dashed line in the background. Transparency layers make it very easy to add shadows to whole groups of objects. As their name implies, you can also use transparency layers to properly handle alpha compositing (transparency) of multiple objects at the same time by setting the alpha value for the context before you begin the transparency layer. Call CGContextSetAlpha() before you call CGContextBeginTransparencyLayer() and the contents of the layer will be composited back into the context with that alpha value when you end the layer. To see this in action, add the following call right before you begin the layer:

   CGContextSetAlpha( currentContext, 0.5 );

Now the whole figure eight has faded out and you can see some of the black dashed line running through the middle (Figure 12). You can also see the faint outline of the figure's shadow through the red fill on the left side.

Wrap Up

I hope you've enjoyed our brief exploration of Quartz 2D. There's so much power and elegance in the API, you really need to sit down and play with it for a while before you get a feel for what it can do. With any luck, I've given you enough of a taste of Quartz 2D that you're ready to go off and experiment on your own. Enjoy!

David Hill is a freelance writer living in College Station, Texas. In a former life, he worked in Apple's Developer Technical Support group helping developers print, draw, and write games. In his free time he dabbles in screen savers and other esoteric topics.