Intro to Quartz II
This tutorial is the second entry in the
Introduction to Quartz series.
Intro to Quartz Part I describes ideas that are essential to understand before reading this tutorial. Even if you've read it, you may want to review first.
This tutorial explains how to create and use custom views, how to construct paths using NSBezierPath, and touches on a variety of topics related to using images with the NSImage class.
This tutorial is written and illustrated by
Scott Stevenson
Copyright © 2006 Scott Stevenson
Custom Views
A custom view is a subclass of NSView which serves a "blank canvas" for your drawing code. Once you have created the view class, you add drawing code using rects, paths and images in the drawRect method.
To create a new view class in your project, choose File > New File in Xcode and select Objective-C NSView subclass
After the class file is created, you drag the header file to the NIB window in Interface Builder so it knows about the class.
Now the class has been added to the NIB file and can be used in a custom view.
Using a Custom View
Once the view has been added to the NIB file, open the Interface Builder palette and drag the CustomView icon out onto your application window.
While the custom view is still selected, bring up the inspector andchoose MyView from the Custom Class inspector dropdown.
The custom view now uses the MyView class. You should also selectSize from the inspector dropdown at this point to configure the sizing to your liking.
The view will not display anything until drawing code is added todrawRect method in the MyView class.
In the above screenshot, we added a 210x210 rect and filled it using a blue NSColor.
We implemented isFlipped to return YES so that the coordinates start in the upper-left instead of the bottom-left.
Paths
Rects can be used for basic graphics, but paths allow for much more complex shapes. The NSBezierPath class is used to create paths in Cocoa.
Paths are mutable, so they can be changed or combined at any time. Path objects can draw themselves into a view. Here are some examples:
Paths can contain curved lines, arcs and rectanges. Each of these examples were drawn to the view by sending the stroke message to the path object.
To create a curved line, you provide a start point, and end point, and two "control" points which act as gravity on the line shape. Control points are not needed for simple straight lines.
Filled Paths
Paths can be filled in addition to being stroked. The following examples first use the fill method with a white NSColor set, then stroke the path with a gray color set.
The paths are filled before being stroked so that the lines are visible.
Creating Paths
The following examples show how to create paths. All of the code assumes a flipped view with coordinates starting in the upper-left.
NSBezierPath * path = [NSBezierPath bezierPath];
[path setLineWidth: 4];
NSPoint startPoint = { 21, 21 };
NSPoint endPoint = { 128,128 };
[path moveToPoint: startPoint];
[path curveToPoint: endPoint
controlPoint1: NSMakePoint ( 128, 21 )
controlPoint2: NSMakePoint ( 21,128 )];
[[NSColor whiteColor] set];
[path fill];
[[NSColor grayColor] set];
[path stroke];
Here's an example of appending a path to an existing path. The path being added is an arc:
NSBezierPath * path = [NSBezierPath bezierPath];
[path setLineWidth:4];
NSPoint center = { 128,128 };
[path moveToPoint: center];
[path appendBezierPathWithArcWithCenter: center
radius: 64
startAngle: 0
endAngle: 321];
[[NSColor whiteColor] set];
[path fill];
[[NSColor grayColor] set];
[path stroke];
It's also easy to create a bezier path from a basic rect:
NSPoint origin = { 21,21 };
NSRect rect;
rect.origin = origin;
rect.size.width = 128;
rect.size.height = 128;
NSBezierPath * path;
path = [NSBezierPath bezierPathWithRect:rect];
[path setLineWidth:4];
[[NSColor whiteColor] set];
[path fill];
[[NSColor grayColor] set];
[path stroke];
Complex Path Construction
The following examples incrementally build and draw several paths to construct the final image. All of the code goes into the custom view'sdrawRect method.
First, we start by creating a basic oval in the center of the view.
// setup basic size and color properties
float dm = 81 * 2;
float rd = dm * 0.50;
float qt = dm * 0.25;
NSColor * white = [NSColor whiteColor];
NSColor * black = [NSColor blackColor];
NSBezierPath *path1, *path2, *path3, *path4;
// find the center of the view
float center = [self bounds].size.width * 0.50;
float middle = [self bounds].size.height * 0.50;
// create a rect in the center
NSPoint origin = { center - rd, middle - rd };
NSRect mainOval = { origin.x, origin.y, dm, dm };
// create a oval bezier path using the rect
path1 = [NSBezierPath bezierPathWithOvalInRect:mainOval];
[path1 setLineWidth:2.18];
// draw the path
[white set];[path1 fill];
[black set];[path1 stroke];
Next, we define a path to overlay on the first one. The path is built in three parts, by appending three different arc paths to the original object.
Note how we build the ellipse in the top half by negating the clockwiseoption.
// overlay a new path to draw the right side
path2 = [NSBezierPath bezierPath];
// arc from the center to construct right side
NSPoint mainOvalCenter = { center, middle };
[path2 appendBezierPathWithArcWithCenter: mainOvalCenter
radius: rd
startAngle: 90
endAngle: 270
clockwise: YES];
// add a half-size arc at the top: counter clockwise
NSPoint curveOneCenter = { center, origin.y+qt };
[path2 appendBezierPathWithArcWithCenter: curveOneCenter
radius: qt
startAngle: 270
endAngle: 90
clockwise: NO];
// add a half-size arc in the bottom half
NSPoint curveTwoCenter = { center, origin.y+rd+qt };
[path2 appendBezierPathWithArcWithCenter: curveTwoCenter
radius: qt
startAngle: 270
endAngle: 90
clockwise: YES];
// fill the path on the right side with black
[black set];[path2 fill];
Finally, we build the paths for the two internal ellipses.
// calculate the size for each ellipses
float dotDm = ( qt * 0.618 );
float dotRd = ( dotDm * 0.5 );
// create a rect at the center of the top section
NSRect rect3 = NSMakeRect ( center - dotRd,
origin.y + (qt - dotRd),
dotDm,
dotDm );
// create an oval with the rect and fill it with black
path3 = [NSBezierPath bezierPathWithOvalInRect: rect3];
[black set];[path3 fill];
// copy the rect for the top ellipse and adjust the y axis
NSRect rect4 = rect3;
rect4.origin.y = NSMaxY(mainOval) - (qt + dotRd);
// create an oval with the rect and fill it with white
path4 = [NSBezierPath bezierPathWithOvalInRect: rect4];
[white set];[path4 fill];
The final result in our custom view.
Images
Cocoa's basic image class is
NSImage. An image can draw itself into a view at various sizes and levels of opacity, or can be written to disk.
Image objects can be created from files on disk, loaded from data in memory, imported from the pasteboard, or drawn on the fly.
Each NSImage instance manages a series of
NSImageRep objects which are versions of the original image data suited to different contexts.
NSImage will automatically choose a representation when you draw into a view, but you can also use an image rep directly. NSBitmapImageRepis perhaps the most common.
Create and Display Images
Creating an NSImage from a file on disk and drawing it into a view is as simple as calling initWithContentsOfFile followed by drawInRect. To make things look nice, we'll center the image in the view and draw a border around it.
First, we need to use NSImageInterpolationHigh to to get smooth bitmap scaling, then calculate the origin of the rect to draw the image in.
[[NSGraphicsContext currentContext]
setImageInterpolation: NSImageInterpolationHigh];
NSSize viewSize = [self bounds].size;
NSSize imageSize = { 250, 156 };
NSPoint viewCenter;
viewCenter.x = viewSize.width * 0.50;
viewCenter.y = viewSize.height * 0.50;
NSPoint imageOrigin = viewCenter;
imageOrigin.x -= imageSize.width * 0.50;
imageOrigin.y -= imageSize.height * 0.50;
NSRect destRect;
destRect.origin = imageOrigin;
destRect.size = imageSize;
We load the image from disk and flip it since our view uses a flipped coordinate system. Once it's loaded, we draw it to the destination rect, than draw a border around the same rect.
NSString * file = @"/Library/Desktop Pictures/Plants/Leaf Curl.jpg";
NSImage * image = [[NSImage alloc] initWithContentsOfFile:file];
[image setFlipped:YES];
[image drawInRect: destRect
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];
NSBezierPath * path = [NSBezierPath bezierPathWithRect:destRect];
[path setLineWidth:3];
[[NSColor whiteColor] set];
[path stroke];
[image release];
Here's the final result drawn into the custom view.
In this example, the image is loaded from disk right before being drawn to the view. This makes the code easier to follow, but it's very inefficient and makes window resizing very slow.
A better approach is to load the image from disk once and store it in an instance variable for drawing later. One of the following examples demonstrates that.
Overlay Images with Transparency
Cocoa can easily draw images as partially transparent, as seen in the following example. First, we need to calculate the rects that we want to draw into, centering the images in the view.
[[NSGraphicsContext currentContext]
setImageInterpolation: NSImageInterpolationHigh];
NSSize viewSize = [self bounds].size;
NSPoint viewCenter;
viewCenter.x = viewSize.width * 0.50;
viewCenter.y = viewSize.height * 0.50;
NSSize large = { 250, 156 };
NSSize small = { 125, 78 };
NSPoint origin = viewCenter;
origin.x -= (large.width+small.width) * 0.5;
origin.y -= large.height * 0.5;
// calculate the main image rect
NSRect largeRect;
largeRect.origin = origin;
largeRect.size = large;
// move to the right and resize
NSRect smallRect1 = largeRect;
smallRect1.origin.x += large.width;
smallRect1.size = small;
// move down
NSRect smallRect2 = smallRect1;
smallRect2.origin.y += small.height;
Next we need to load the images from disk and flip them to match our coordinate system.
NSString * file1 = @"/Library/Desktop Pictures/Plants/Purple Frond.jpg";
NSString * file2 = @"/Library/Desktop Pictures/Plants/Agave.jpg";
NSImage * image1 = [[NSImage alloc] initWithContentsOfFile:file1];
NSImage * image2 = [[NSImage alloc] initWithContentsOfFile:file2];
[image1 setFlipped:YES];
[image2 setFlipped:YES];
Now each image draws itself into the view twice: once in the main large rect, and once in a smaller rect. A single image object can draw itself any number of times.
The images are drawn on top of each other in the large rect, with 80% and60% opacity, respectively. After that, each image draws itself into a separate smaller rect, fully opaque.
[image1 drawInRect: largeRect
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 0.8];
[image2 drawInRect: largeRect
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 0.6];
[image1 drawInRect: smallRect1
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];
[image2 drawInRect: smallRect2
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];
Finally, we draw borders around the images.
[[NSColor whiteColor] set];
NSBezierPath *path = [NSBezierPath bezierPathWithRect: largeRect];
[path appendBezierPathWithRect: smallRect1];
[path appendBezierPathWithRect: smallRect2];
[path setLineWidth:2.5];
[path stroke];
[image1 release];
[image2 release];
Here's the final result.
Resizing the window is still slow in this example, because we're still loading the image from disk frequently. The next example focuses on some optimization techniques.
Draw Directly to an Image
Hint: This technique is also useful if your application needs to generate images dynamically, or superimpose content on top of an existing image. The results can be written to a file.
We can optimize drawing multiple images to the screen by combining them in into one image, then draw the composite version to the view.
This is called drawing into an "offscreen image" or "offscreen buffer", because the pixels are collected for later use instead of being displayed on the screen immediately.
To do this, we need to create an instance variable in the view namedcompositeImage, and add a method to generate the image. The generated image will be used in drawRect.
Below is the first part of the code for createCompositeImage. First, we set up an array of image file names, and calculate the total size needed to hold all of them.
- (void)createCompositeImage {
NSString * folder = @"/Library/Desktop Pictures/";
NSArray * files = [NSArray arrayWithObjects:
@"Plants/Petals.jpg",
@"Nature/Flowing Rock.jpg",
@"Plants/Maple.jpg", nil];
// make a size big enough to hold all images
int count = [files count];
NSRect rect = { 0,0, 150, 94};
NSSize compositeSize;
compositeSize.width = (rect.size.width * count);
compositeSize.height = rect.size.height;
Now we'll create the compositeImage object and draw into it using the
lockFocus method. Once lockFocus is called, all drawing goes directly into the image object until
unlockFocus is called.
Locking focus creates a new graphics context and also creates a
new coordinate system where (0,0) is the upper-left corner of the image, rather than the view itself. For clarity, it's best to indent the code between locking and unlocking focus.
The code below assumes standard accessors for compositeImage exist.
// -createCompositeImage continued...
NSImage * compositeImage;
compositeImage = [[NSImage alloc] initWithSize:compositeSize];
[compositeImage lockFocus];
// this image has its own graphics context, so
// we need to specify high interpolation again
[[NSGraphicsContext currentContext]
setImageInterpolation: NSImageInterpolationHigh];
int i;
NSImage * image;
NSString * file;
for ( i = 0; i < count; i++ )
{
// load the image from disk and draw it
// into the composite image
file = [folder stringByAppendingString:
[files objectAtIndex:i]];
image = [[NSImage alloc] initWithContentsOfFile:file];
[image setFlipped:YES];
[image drawInRect: rect
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];
[image release]; image = nil;
rect.origin.x += rect.size.width; // move right
}
[compositeImage unlockFocus];
[self setCompositeImage:compositeImage];
[compositeImage release];
} // end -createCompositeImage
Now we'll move on to drawing the composite image into the view.
Display the Composite Image
The composite image is drawn into the view in the NSView drawRectmethod, as shown below.
- (void) drawRect: (NSRect)aRect {
NSImage * compositeImage = [self compositeImage];
if ( !compositeImage )
{
// if the image is nil, we need to create it
[self createCompositeImage];
compositeImage = [self compositeImage];
}
// find the center of the view
NSSize viewSize = [self bounds].size;
NSPoint viewCenter;
viewCenter.x = viewSize.width * 0.50;
viewCenter.y = viewSize.height * 0.50;
// calculate image rect to draw the image to
NSSize size = [compositeImage size];
NSRect rect;
rect.origin.x = viewCenter.x - (size.width * 0.50);
rect.origin.y = viewCenter.y - (size.height * 0.50);
rect.size = size;
// draw composite image
[compositeImage drawInRect: rect
fromRect: NSZeroRect
operation: NSCompositeSourceOver
fraction: 1.0];
// draw border
NSBezierPath * path = [NSBezierPath bezierPathWithRect:rect];
[path setLineWidth:2.5];
[[NSColor whiteColor] set];
[path stroke];
} // end of -drawRect
Here's our final result. You'll notice that resizing the window in this example is much faster than in the previous examples because we're only loading the image data once.
It's only necessary to draw into an offscreen image if you want to create a combination of multiple images. Individual images can just be set as instance variables and drawn as is.
Wrap Up
We've covered some intermediate Quartz topics here. If you'd like to see more tutorials like this, please make a donation below. The source code from this tutorial is included in the following zip file.
Please consider the download your
thank you gift for making a donation. It also contains a few small extras, including many more comments and an example of using Bindings and the Objective-C runtime to dynamically select a method to run.
Show me a garden that's bursting into life.