---

Introduction to Quartz 2D Programming Guide

Contents:

Who Should Read This Document?
Organization of This Document
See Also

Quartz 2D is an advanced, two-dimensional drawing engine accessible from all Mac OS X application environments outside of the kernel. Quartz 2D is based on industry standards—PostScript and PDF. Quartz 2D uses ColorSync for high-quality color management and Apple Type Services (ATS) for font rendering. It provides low-level, lightweight 2D rendering with unmatched output fidelity regardless of display or printing device. Quartz 2D is resolution- and device-independent; you don’t need to think about the final destination when you use the Quartz 2D application programming interface (API) for drawing.

The Quartz 2D API is easy to use and provides access to powerful features such as transparency layers, path-based drawing, offscreen rendering, advanced color management, anti-aliased rendering, and PDF document creation, display, and parsing.

The Quartz 2D API is part of the Core Graphics framework, so you may see Quartz referred to as Core Graphics or, simply, CG.

Who Should Read This Document?

This document is intended for developers who need to perform any of the following tasks:

• Draw graphics. Safari and iTunes are two of the applications that use Quartz 2D to display graphics, including PDF files and bitmap images (JPEG, PNG, GIF, and so on).

• Provide graphics editing capabilities in an application. Mathematica, Microsoft Office, and Keynote use Quartz 2D to provide graphics editing capabilities and use transparency to achieve stunning effects.

• Create or display bitmap images. iPhoto is just one of the many applications that use Quartz 2D to create and display bitmap images. Bringing image data into Quartz and exporting data from it is even easier using the image I/O functions added in Mac OS X v10.4.

• Work with PDF documents. You can open or create PDF documents, access PDF metadata, parse PDF documents, and add secure features to PDF.

• Convert PostScript files to PDF documents. Preview uses Quartz 2D for its built-in PostScript-to-PDF document conversion.

Quartz 2D is useful for developers who use the Carbon or Cocoa frameworks, because:

• If you use the Carbon framework, Quartz 2D replaces QuickDraw. You can also use the user interface APIs based on Quartz 2D, which include the HIObject-based APIs—HIObject, HIView, and HIToolbar.

• If you use the Cocoa framework, Quartz 2D lets you access the graphics system at a very low level. The NSView-based graphics system is built on the capabilities of Quartz 2D. You can use any Quartz function in a Cocoa application.

Organization of This Document

This document is organized into the following chapters:

• “Overview of Quartz 2D” introduces Quartz 2D and discusses its relationship to other components of Mac OS X. It describes the page, drawing destinations, Quartz opaque data types, graphics states, coordinates, memory management, and takes a look at how Quartz works “under the hood.”

• “Graphics Contexts” describes graphics contexts and provides step-by-step instructions for creating all flavors of graphics contexts.

• “Paths” discusses the basic elements that make up paths, shows how to create and paint them, shows how to set up a clipping area, and shows how blend modes affect painting.

• “Color and Color Spaces” discusses color values, using alpha for transparency, and describes how to create a color space, set colors, create color objects, and set rendering intent.

• “Transforms” describes the current transformation matrix and explains how to modify it, shows how to set up affine transforms, how to convert between user and device space, and provides background information on the mathematical operations that Quartz performs.

• “Patterns” defines what a pattern is and its parts, tells how Quartz renders them, and shows how to create colored and stenciled patterns.

• “Shadows” describes what shadows are, how they work, and shows how to paint with them.

• “Gradients” discusses axial and radial gradients and shows how to create and use CGShading and CGGradient objects.

• “Transparency Layers” gives examples of what transparency layers look like, discusses how they work, and provides step-by-step instructions for implementing them.

• “Data Management” discusses how to move data into and out of Quartz, and between Core Image and Quartz. It provides an overview of the Image I/O functions added in Mac OS X v10.4.

• “Bitmap Images and Image Masks” describes what makes up a bitmap image definition and shows how to use a bitmap image as a Quartz drawing primitive. It also describes masking techniques you can use on images and shows the various effects you can achieve by using blend modes when drawing images.

• “CGLayer Drawing” describes how to create and use drawing layers to achieve high-performance patterned drawing or to draw offscreen.

• “PDF Document Creation, Viewing, and Transforming” shows how to open and view PDF documents, apply transforms to them, create a PDF file, access PDF metadata, add links, and add security features (such as password protection).

• “PDF Document Parsing” describes how to use CGPDFScanner and CGPDFContentStream objects to parse and inspect PDF documents.

• “PostScript Conversion” gives an overview of the functions you can use to convert a PostScript file to a PDF document.

• “Python Bindings for Quartz 2D” provides a brief overview of the Python scripting language and the Quartz 2D API for Python, and describes some of the useful tasks you can accomplish using Python scripts and Quartz 2D.

• “Text” describes Quartz 2D low-level support for text and glyphs, and alternatives that provide higher-level and Unicode text support. It also discusses how to copy font variations.

• “Glossary” defines the terms used in this guide.

See Also

These items are essential reading for anyone using Quartz 2D:

• Quartz 2D Reference Collection, organized by header file, provides a complete reference to the Quartz 2D application programming interface.

• Sample code that demonstrates how to use graphics routines. This code is available after you install the Xcode Tools CD in /Developer/Examples/Quartz.

• Image I/O Programming Guide describes how to use the Image I/O framework to read and write image data.

• Color Management Overview is a brief introduction to the principles of color perception, color spaces, and color management systems.

• Mailing lists. Join the quartz-dev mailing list to discuss problems using Quartz 2D in Mac OS X.

• Technical notes and Technical Q&As. Keep up to date on the latest technical information by visiting the Graphics & Imaging Quartz Reference Library.

• Programming With Quartz: 2D and PDF Graphics in Mac OS X provides in-depth information on using Quartz. This book is current through Mac OS X v10.4 and includes examples that show how to support earlier versions of Mac OS X as well as how to use the features introduced in v10.4. The sample code associated with this book is available from the publisher.

These reference guides are for technologies directly related to Quartz:

• The latest version o PDF Reference, available from partners.adobe.com, is the standard reference manual for the PDF file format.

• The PostScript Language Reference Manual (Addison-Wesley), also known as the “Red Book,” is the standard reference manual for the PostScript page description language. PDF is based—in part—on the PostScript imaging model.

These programming guides discuss some of the technologies that are available in Mac OS X v10.4 and that you may want to use along with Quartz 2D:

• Core Image Programming Guide describes the Mac OS X image processing technology and shows how to use the Core Image API.

• Core Video Programming Guide describes the Mac OS X digital video model and shows how to use the Core Video API.

---