Before You Start

Make sure you are using a development environment that supports Quartz, such as Xcode.

Gather up the latest Quartz documentation so that it is readily accessible to you.

• Quartz 2D Programming Guide. If you haven’t read this document yet, at least read the overview and the table of contents so that you know what’s covered in the book. Take a quick scan through the book.

• Quartz 2D Reference Collection. You’ll need to look up function definitions as you start rewriting your code.

Locate the Carbon Sketch application and familiarize yourself with the code and what the application does. By looking at the code, you can get ideas on how to rearchitect your application to use only Quartz for drawing. You can find Carbon Sketch on the ADC Reference Library site:

http://developer.apple.com/samplecode/GraphicsImaging/idxQuartz-title.html#doclist

The application performs many tasks needed in a drawing application. For example, it:

• Draws all artwork using Quartz

• Uses an overlay window to handle selection, dragging, and resizing objects

• Performs hit testing using a 1-pixel bitmap context

• Copy and pastes PDF data using the PasteBoard API

• Uses Quartz Generic color spaces

Analyze Your Code

Analyze your QuickDraw code so that you can understand what needs to change. Then develop a plan before you start reworking your code. Keep in mind that many things have changed in Mac OS X, and especially in Mac OS X v10.4. Technologies other than QuickDraw are deprecated in Mac OS X v10.4, including QuickDraw Text, Display Manager, and Draw Sprockets.

If, after analyzing your code, you plan to stick with the C APIs in the Carbon framework, you may want to use HIView along with Quartz. The HIToolbox offers many technologies that are complementary to Quartz (such as HIShape) and that will ensure that your application is updated for the 21st century.

If you decide to completely rewrite your application in all respects, you might want to think about moving to Cocoa. You can use the Quartz API in any framework outside of the kernel. When you use Cocoa, you can call Quartz directly and you can also use Cocoa drawing methods, which are built on top of Quartz.

As you analyze your code, take a careful look at how you use QuickDraw. Sometimes you’ll find that Quartz provides functional equivalents for your QuickDraw code, but more often than not you’ll need to think differently. Your application will benefit most if you can think beyond QuickDraw. That is, don’t just look for ways to accomplish the same task in Quartz. Take some time to think about how your application currently works and how you might be able to leverage the new capabilities that Mac OS X provides to improve the user experience of your application, not just maintain parity with your QuickDraw version.

General Strategies

The following strategies are useful for revising QuickDraw applications to use Quartz:

1. Think differently, especially for those items that don’t have equivalent functionality in Quartz—such as arithmetic transfer modes, SeedCFill, SearchProcs—but that you still need to find a substitute for.

2. Focus on functionality, not functions. The approach of translating QuickDraw idioms into Quartz won’t work in most cases, especially for calls to CopyBits and the regions functions.

3. Analyze your use of regions to see what functionality each use provides. Then revise the code accordingly. You may have used regions for a variety of purposes; you’ll find alternative strategies throughout this guide. See Regions Replacement Strategies.

4. Analyze your CopyBits calls to see what functionality each call provides. Then revise the code accordingly. You probably used CopyBits and related functions to achieve a number of tasks in QuickDraw; you’ll find alternative strategies throughout this guide. See CopyBits Replacement Strategies.

5. Account for differences between the QuickDraw and Quartz coordinate systems. If you use HIView along with Quartz, make sure you are familiar with how HIView handles coordinates. See Coordinate Space.

6. Use alpha. It’s fully supported in Quartz. See The Alpha Value in Quartz 2D Programming Guide.

7. Convert PICT data to PDF and provide conversion support in your application to handle legacy PICT files that your users may need to open. See Converting PICT Data.

8. Support PDF data for Copy and Paste actions. Only PDF content fully captures Quartz drawing, and you’ll want to ensure fidelity of content. See Converting PICT Data.

9. Save and restore graphics states appropriately. See Graphics State and Global Effects.

10. Revise your hit testing code. See Hit Testing.

11. Think device independence and resolution independence. See Drawing Destinations.

12. Identify the shortcomings of your QuickDraw application to see where you can use new features of Quartz to improve your application.

13. Remove code that compensates for QuickDraw shortcomings. For example, XOR drawing isn’t needed by most applications that use Quartz. The GrafProcs bottleneck tricks simply don’t apply in Quartz.

14. Optimize your code to ensure that your application performs at its best. See Performance.

Regions Replacement Strategies

Regions served many purposes in QuickDraw. You’ll want to analyze your code to see what purpose each use of regions serves.

If you use QuickDraw regions for:

• Drawing shapes, then instead use paths to construct arbitrary shapes and use Quartz convenience functions to draw rectangles, circles, ovals, ellipses, and lines. See Alternatives to QuickDraw Drawing Functions and Constructing and Drawing Shapes. In Quartz, you can draw directly to a destination, or you can use the CGPathRef data type to build up a complex shape that you draw later and reuse anytime you’d like.

• Clipping regions, consider one of the Quartz context clipping functions, such as CGContextClip or CGContextClipToMask. SeeClipping.

• Hit test, then use paths or a 1x1 bitmap graphics context. See Hit Testing.

• Masking, then there are a number of approaches you can take, depending on what you want to accomplish. Consider the Quartz function CGContextClipToMask, take a look at what you can accomplish with blend modes, and for images, consider CGImageMaskCreate, CGImageCreateWithMask, and CGImageCreateWithMaskingColors. See Masking and Color Blend Modes.

If you want to:

• Create a RgnHandle, consider using an HIShape object, which is an abstract shape object that replaces the old QuickDraw region handle. HIShape objects are the preferred way to describe regions in HIView views that use Quartz. See HIShape Reference. If you are not using HIView, take a look at CGPath objects (CGPathRef data type), which you can use to draw reusable shapes. See Constructing and Drawing Shapes.

• Update a region shape, see Updating Regions.

CopyBits Replacement Strategies

Many years of development and optimization made the QuickDraw function CopyBits an exceptionally fast, general-purpose blitter. QuickDraw is based on bitmap graphics, and CopyBits makes perfect sense in that environment. The Quartz imaging model does not provide for pixel drawing operations or bit copying functionality. The fact that Quartz is not based on bits gives rise to its many cool features, including its ability to maintain device and resolution independence. Quartz does have the capability for you to draw bits, should you need to do so, but most of the time you’ll want to adopt strategies for replacing CopyBits, CopyMask, and CopyDeepMask—strategies that leverage Quartz rather than seek parity with QuickDraw.

The functions CopyBits, CopyMask, and CopyDeepMask were used to achieve so many results in QuickDraw that you’ll want to read all the replacement strategies before you decide which course of action to take. If you use the QuickDraw functions CopyBits, CopyMask, or CopyDeepMask for:

• Moving bits from a GWorld to the screen. See Working With Bitmap Image Data and Offscreen Drawing.

• Offscreen drawing, check out the CGLayerRef data type and how to use it with the function CGLayerCreateWithContext. You might also investigate HIViewCreateOffscreenImage. See Using a CGLayer Object for Offscreen Drawing.

• Fast scrolling, consider using HIView to create a scrolling view (see the function HIScrollViewCreate). See HIView Programming Guide and HIView Reference for more information.

• Image animation, use overlay windows. See Using Overlay Windows.

• Highlighting portions of an image, use overlay windows. See Updating Regions.

• Converting from one pixel depth to another, then eliminate code that changes pixel depth. Modern hardware has plenty of memory and rendering horsepower, and there is no longer any motivation to reduce image depth.

• Scaling or resizing an image, you can instead use the Quartz function CGContextDrawImage and then adjust the destination rectangle to get the desired scaling.

• Clipping or cropping an image, consider the Quartz functions CGImageCreateWithImageInRect, CGImageCreateWithMask, and CGContextClipToMask. You can create thumbnail images in Quartz using the function CGImageSourceCreateThumbnailAtIndex. All four functions are introduced in Mac OS X v10.4. See Creating Images in Quartz 2D Programming Guide.

• Color blending using transfer modes, consider using blend modes in Quartz. See Color Blend Modes, which allows blending shapes using translucent color. In Quartz 2D Programming Guide, see Setting Blend Modes and Using Blend Modes With Images.

  Quartz doesn’t have an functions that operate on a per-pixel basis, but Core Image does. If you want to perform image processing on a per pixel basis, you can convert a Quartz image to a Core Image image, perform the operation, and pass the processed image back to Quartz. See Core Image Programming Guide and Moving Data Between Quartz 2D and Core Image in Quartz 2D Programming Guide.

• Creating transparency effects, then use the alpha channel to specify the translucency of a color. See The Alpha Value in Quartz 2D Programming Guide.

• Creating image masks, consider using CGImageMaskCreate. See Masking.

• Storing and retrieving images, then use the Quartz image-source and image-destination functions. These handle the common image file formats in use today, including JPEG, PNG, TIFF, JPEG2000. See CGImageSource Reference, CGImageDestination Reference, and Data Management in Quartz 2D Programming Guide.

• Inverting colors, consider using the exclusion or difference blend modes. In Quartz 2D Programming Guide, see Setting Blend Modes and Using Blend Modes With Images.

• Colorizing an image, consider using blend modes. See Colorizing an Image.