Cocoa Drawing Guide 2006-10-03 Adobe Systems Incorporated in the U.S. Apple Computer, Inc. and/or other countries. © 2005, 2006 Apple Computer, Inc. Helvetica is a registered trademark of All rights reserved. Heidelberger Druckmaschinen AG, available from Linotype Library GmbH. No part of this publication may be reproduced, stored in a retrieval system, or OpenGL is a registered trademark of Silicon transmitted, in any form or by any means, Graphics, Inc. mechanical, electronic, photocopying, Simultaneously published in the United recording, or otherwise, without prior States and Canada. written permission of Apple Computer, Inc., Even though Apple has reviewed this document, with the following exceptions: Any person APPLE MAKES NO WARRANTY OR is hereby authorized to store documentation REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS on a single computer for personal use only DOCUMENT, ITS QUALITY, ACCURACY, and to print copies of documentation for MERCHANTABILITY, OR FITNESS FOR A PARTICULAR PURPOSE. AS A RESULT, THIS personal use provided that the DOCUMENT IS PROVIDED “AS IS,” AND documentation contains Apple’s copyright YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND notice. ACCURACY. The Apple logo is a trademark of Apple IN NO EVENT WILL APPLE BE LIABLE FOR Computer, Inc. DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES Use of the “keyboard” Apple logo RESULTING FROM ANY DEFECT OR INACCURACY IN THIS DOCUMENT, even if (Option-Shift-K) for commercial purposes advised of the possibility of such damages. without the prior written consent of Apple THE WARRANTY AND REMEDIES SET may constitute trademark infringement and FORTH ABOVE ARE EXCLUSIVE AND IN LIEU OF ALL OTHERS, ORAL OR WRITTEN, unfair competition in violation of federal EXPRESS OR IMPLIED. No Apple dealer, agent, and state laws. or employee is authorized to make any modification, extension, or addition to this No licenses, express or implied, are granted warranty. with respect to any of the technology Some states do not allow the exclusion or described in this document. Apple retains limitation of implied warranties or liability for incidental or consequential damages, so the all intellectual property rights associated above limitation or exclusion may not apply to with the technology described in this you. This warranty gives you specific legal rights, and you may also have other rights which document. This document is intended to vary from state to state. assist application developers to develop applications only for Apple-labeled or Apple-licensed computers. Every effort has been made to ensure that the information in this document is accurate. Apple is not responsible for typographical errors. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, Carbon, Cocoa, ColorSync, Mac, Mac OS, Macintosh, Quartz, QuickDraw, QuickTime, and Xcode are trademarks of Apple Computer, Inc., registered in the United States and other countries. Objective-C is a registered trademark of NeXT Software, Inc. Adobe, Acrobat, and PostScript are trademarks or registered trademarks of Contents Introduction Introduction to Cocoa Drawing Guide 13 Who Should Read This Document 13 Organization of This Document 13 See Also 14 Chapter 1 Overview of Cocoa Drawing 15 Cocoa Drawing Support 15 The Painter’s Model 16 The Drawing Environment 17 The Graphics Context 17 The Graphics State 17 The Coordinate System 18 Transforms 18 Color and Color Spaces 19 Basic Drawing Elements 19 Geometry Support 19 Shape Primitives 20 Images 21 Text 22 Views and Drawing 22 Common Drawing Tasks 23 Chapter 2 Graphics Contexts 25 Graphics Context Basics 25 The Current Context 26 Graphics State Information 27 Screen Canvases and Print Canvases 29 Graphics Contexts and Quartz 30 Modifying the Current Graphics State 30 Setting Colors and Patterns 31 Setting Path Attributes 31 Setting Text Attributes 31 Setting Compositing Options 32 Setting the Clipping Region 33 Setting the Anti-aliasing Options 35 3 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Creating Graphics Contexts 36 Creating a Screen-Based Context 37 Creating a PDF or PostScript Context 37 Threading and Graphics Contexts 38 Chapter 3 Coordinate Systems and Transforms 39 Coordinate Systems Basics 39 Local Coordinate Systems 39 Points and Pixels 40 Transform Basics 44 The Identity Transform 44 Transformation Operations 44 Transformation Ordering 47 Transform Mathematics 49 Using Transforms in Your Code 50 Creating and Applying a Transform 50 Undoing a Transformation 50 Transforming Coordinates 51 Converting from Window to View Coordinates 52 Flipped Coordinate Systems 52 Using Flipped Coordinates 53 Cocoa Use of Flipped Coordinates 54 Creating a Flip Transform 55 Flipping Images 55 Flipping Text 56 Chapter 4 Color and Transparency 57 About Color and Transparency 57 Color Models and Color Spaces 57 Color Objects 58 Color Component Values 58 Transparency 58 Pattern Colors 59 Color Lists 59 Color Matching 60 Creating Colors 60 Working with Colors 61 Applying Colors to Drawn Content 61 Applying Color to Text 61 Getting the Components of a Color 62 Choosing Colors 62 Working with Color Spaces 63 Converting Between Color Spaces 63 Mapping Physical Colors to a Color Space 63 4 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 5 Paths 65 Path Building Blocks 65 The NSBezierPath Class 66 Path Elements 66 Subpaths 67 Path Attributes 68 Winding Rules 73 Manipulating Geometric Types 75 Drawing Fundamental Shapes 76 Adding Points 76 Adding Lines and Polygons 77 Adding Rectangles 78 Adding Ovals and Circles 78 Adding Arcs 79 Adding Bezier Curves 81 Adding Text 81 Drawing the Shapes in a Path 82 Drawing Rectangles 83 Working with Paths 84 Building Paths 84 Improving Rendering Performance 84 Manipulating Individual Path Elements 86 Transforming a Path 87 Creating a CGPathRef From an NSBezierPath Object 87 Detecting Mouse Hits on a Path 88 Chapter 6 Images 91 Image Basics 91 Image Representations 92 Images and Caching 94 Image Size and Resolution 96 Images and Flipped Coordinates 97 Supported Image File Formats 98 Basic Formats 98 TIFF Compression 98 Support for Other File Formats 99 Guidelines for Using Images 100 Creating NSImage Objects 100 Loading an Existing Image 101 Loading a Named Image 101 Drawing to an Image 102 Creating a Bitmap 102 Creating a PDF or EPS Image Representation 105 Using a Quartz Image to Create an NSImage 106 5 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Working with Images 106 Drawing Images into a View 106 Creating an OpenGL Texture 107 Applying Core Image Filters 108 Converting a Bitmap to a Different Format 109 Associating a ColorSync Profile With an Image 109 Converting Between Color Spaces 110 Premultiplying Alpha Values for Bitmaps 114 Creating New Image Representation Classes 114 Chapter 7 Text 117 Text Attributes 117 Simple Text Drawing 117 Advanced Text Drawing 118 Chapter 8 Advanced Drawing Techniques 119 Adding Shadows to Drawn Paths 119 Creating Gradient Fills 120 Drawing to the Screen 121 Capturing the Screen 122 Full-Screen Drawing in OpenGL 122 Full-Screen Drawing in Cocoa 123 Disabling Screen Updates 125 Using NSTimer for Animated Content 125 Using Cocoa Animation Objects 125 Optimizing Your Drawing Code 126 Draw Minimally 126 Avoid Forcing Synchronous Updates 126 Reuse Your Objects 126 Minimize State Changes 127 Chapter 9 Incorporating Other Drawing Technologies 129 Using Quartz in Your Application 129 Using Quartz Features 129 Graphics Type Conversions 130 Getting a Quartz Graphics Context 131 Creating a Cocoa Graphics Context Using Quartz 131 131 Modifying the Graphics State 132 Using OpenGL in Your Application 132 Using NSOpenGLView 132 Creating an OpenGL Graphics Context 133 Using QuickTime in Your Application 134 6 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Using the QuickTime Kit 134 Using QuickTime C-Based Functions 134 Using Quartz Composer Compositions 135 Document Revision History 137 Index 139 7 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS 8 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. Figures, Tables, and Listings Chapter 1 Overview of Cocoa Drawing 15 Figure 1-1 The painter’s model 16 Figure 1-2 Examples of shape primitives 20 Figure 1-3 Examples of bitmap images 21 Figure 1-4 Examples of text 22 Table 1-1 Primitive data types 19 Table 1-2 Common tasks and solutions 24 Chapter 2 Graphics Contexts 25 Figure 2-1 Compositing operations in Cocoa 33 Figure 2-2 Clipping paths and winding rules 34 Figure 2-3 A comparison of aliased and anti-aliased content 36 Table 2-1 Graphics state information 27 Chapter 3 Coordinate Systems and Transforms 39 Figure 3-1 Coordinate systems on the screen 40 Figure 3-2 Translating content 45 Figure 3-3 Scaling content 46 Figure 3-4 Rotated content 46 Figure 3-5 Transform ordering 48 Figure 3-6 Basic transformation matrix 49 Figure 3-7 Mathematical conversion of coordinates 49 Figure 3-8 Normal and flipped coordinate axes 53 Listing 3-1 Adjusting coordinates for resolution independent interfaces 43 Listing 3-2 Flipping the coordinate system manually 55 Chapter 4 Color and Transparency 57 Figure 4-1 Drawing with a pattern 59 Table 4-1 Methods for changing color attributes 61 Table 4-2 Quartz rendering intents 63 Chapter 5 Paths 65 Figure 5-1 Path elements for a complex path 67 9 2006-10-03 | © 2005, 2006 Apple Computer, Inc. All Rights Reserved. FIGURES, TABLES, AND LISTINGS Figure 5-2 Line cap styles 69 Figure 5-3 Line join styles 70 Figure 5-4 Line dash patterns 71 Figure 5-5 Flatness effects on curves 72 Figure 5-6 Miter limit effects 73 Figure 5-7 Applying winding rules to a path 74 Figure 5-8 Creating arcs 80 Figure 5-9 Cubic Bezier curve 81 Figure 5-10 Stroking and filling a path.