Quartz 2D Reference Collection 2006-05-23 Simultaneously published in the United Apple Computer, Inc. States and Canada. © 2006 Apple Computer, Inc. Even though Apple has reviewed this document, All rights reserved. APPLE MAKES NO WARRANTY OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS No part of this publication may be DOCUMENT, ITS QUALITY, ACCURACY, MERCHANTABILITY, OR FITNESS FOR A reproduced, stored in a retrieval system, or PARTICULAR PURPOSE. AS A RESULT, THIS transmitted, in any form or by any means, DOCUMENT IS PROVIDED “AS IS,” AND mechanical, electronic, photocopying, YOU, THE READER, ARE ASSUMING THE ENTIRE RISK AS TO ITS QUALITY AND recording, or otherwise, without prior ACCURACY. written permission of Apple Computer, Inc., IN NO EVENT WILL APPLE BE LIABLE FOR with the following exceptions: Any person DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES is hereby authorized to store documentation RESULTING FROM ANY DEFECT OR on a single computer for personal use only INACCURACY IN THIS DOCUMENT, even if and to print copies of documentation for advised of the possibility of such damages. personal use provided that the THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND IN documentation contains Apple’s copyright LIEU OF ALL OTHERS, ORAL OR WRITTEN, notice. EXPRESS OR IMPLIED. No Apple dealer, agent, or employee is authorized to make any The Apple logo is a trademark of Apple modification, extension, or addition to this Computer, Inc. warranty. Some states do not allow the exclusion or Use of the “keyboard” Apple logo limitation of implied warranties or liability for (Option-Shift-K) for commercial purposes incidental or consequential damages, so the above limitation or exclusion may not apply to without the prior written consent of Apple you. This warranty gives you specific legal may constitute trademark infringement and rights, and you may also have other rights which vary from state to state. unfair competition in violation of federal and state laws. No licenses, express or implied, are granted with respect to any of the technology described in this document. Apple retains all intellectual property rights associated with the technology described in this document. This document is intended to 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, ColorSync, Mac, Mac OS, Pages, Quartz, QuickDraw, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. Adobe, Acrobat, and PostScript are trademarks or registered trademarks of Adobe Systems Incorporated in the U.S. and/or other countries. OpenGL is a registered trademark of Silicon Graphics, Inc. Contents Introduction Introduction 11 Part I Opaque Types 13 Chapter 1 CGBitmapContext Reference 15 Introduction 15 Functions by Task 15 Functions 16 Chapter 2 CGColor Reference 23 Introduction 23 Functions by Task 23 Functions 24 Data Types 30 Chapter 3 CGColorSpace Reference 31 Introduction 31 Functions by Task 31 Functions 33 Data Types 42 Constants 43 Chapter 4 CGContext Reference 47 Introduction 47 Functions by Task 47 Functions 54 Data Types 116 Constants 117 Chapter 5 CGDataConsumer Reference 125 Introduction 125 Functions 125 Callbacks 128 3 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Data Types 129 Chapter 6 CGDataProvider Reference 131 Introduction 131 Functions 131 Callbacks by Task 136 Callbacks 136 Data Types 142 Chapter 7 CGFont Reference 145 Introduction 145 Functions 145 Data Types 151 Constants 152 Chapter 8 CGFunction Reference 155 Introduction 155 Functions 155 Callbacks 157 Data Types 159 Chapter 9 CGGLContext Reference 161 Introduction 161 Functions 161 Chapter 10 CGImage Reference 163 Introduction 163 Functions by Task 163 Functions 165 Data Types 179 Constants 180 Chapter 11 CGImageDestination Reference 185 Introduction 185 Functions 185 Data Types 190 Constants 190 4 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 12 CGImageSource Reference 193 Introduction 193 Functions by Task 193 Functions 195 Data Types 202 Constants 203 Chapter 13 CGLayer Reference 229 Introduction 229 Functions 230 Data Types 234 Chapter 14 CGPath Reference 235 Introduction 235 Functions by Task 235 Functions 237 Callbacks 252 Data Types 252 Constants 254 Chapter 15 CGPattern Reference 257 Introduction 257 Functions 257 Callbacks 260 Data Types 261 Constants 262 Chapter 16 CGPDFArray Reference 265 Introduction 265 Functions 265 Data Types 272 Chapter 17 CGPDFContentStream Reference 273 Introduction 273 Functions by Task 273 Functions 274 Data Types 277 5 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Chapter 18 CGPDFContext Reference 279 Introduction 279 Functions 279 Constants 283 Chapter 19 CGPDFDictionary Reference 289 Introduction 289 Functions by Task 289 Functions 290 Callbacks 297 Data Types 297 Chapter 20 CGPDFDocument Reference 299 Introduction 299 Functions by Task 299 Functions 301 Data Types 313 Chapter 21 CGPDFObject Reference 315 Introduction 315 Functions 315 Data Types 317 Constants 318 Chapter 22 CGPDFOperatorTable Reference 321 Introduction 321 Functions by Task 321 Functions 322 Callbacks 324 Data Types 324 Chapter 23 CGPDFPage Reference 325 Introduction 325 Functions 325 Data Types 330 Constants 330 Chapter 24 CGPDFScanner Reference 333 Introduction 333 6 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Functions by Task 333 Functions 334 Data Types 341 Chapter 25 CGPDFStream Reference 343 Introduction 343 Functions 343 Data Types 344 Constants 345 Chapter 26 CGPDFString Reference 347 Introduction 347 Functions by Task 347 Functions 348 Data Types 349 Chapter 27 CGPSConverter Reference 351 Introduction 351 Functions 351 Callbacks 354 Data Types 357 Chapter 28 CGShading Reference 359 Introduction 359 Functions 359 Data Types 363 Part II Other References 365 Chapter 29 CGAffineTransform Reference 367 Introduction 367 Functions by Task 367 Functions 368 Data Types 377 Constants 379 Chapter 30 CGGeometry Reference 381 Introduction 381 Functions by Task 381 7 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CONTENTS Functions 383 Data Types 396 Constants 397 Document Revision History 399 Index 401 8 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. Tables Chapter 12 CGImageSource Reference 193 Table 12-1 208 Chapter 14 CGPath Reference 235 Table 14-1 Path elements in a rectangular subpath 253 9 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. TABLES 10 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. INTRODUCTION Introduction Framework /System/Library/Frameworks/ApplicationServices.framework Header file directories /System/Library/Frameworks/ApplicationServices.framework/Headers Quartz 2D is an API that makes the Quartz advanced drawing engine accessible from all Mac OS X application environments outside of the kernel. It provides low-level, lightweight 2D rendering with unmatched output fidelity regardless of the display or printing device. The Quartz 2D API supports transparency layers, path-based drawing, transformations, offscreen rendering, advanced color management, anti-aliased rendering, patterns, shadings, image data management, image creation, masking, and PDF document creation, display, and parsing. 11 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. INTRODUCTION Introduction 12 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. PART I Opaque Types 13 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. PART I Opaque Types 14 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 CGBitmapContext Reference Derived From: CGContextRef (page 116) Framework: ApplicationServices/ApplicationServices.h Declared in: CGBitmapContext.h Introduction The CGBitmapContext header file defines functions that create and operate on a Quartz bitmap graphics context. A bitmap graphics context is a type of CGContextRef (page 116) that is used for drawing bitmaps. The functions in this reference operate only on Quartz bitmap graphics contexts created using the functionCGBitmapContextCreate (page 16). The number of components for each pixel in a bitmap graphics context is specified by a color space (defined by a CGColorSpaceRef (page 42), which includes RGB, grayscale, and CMYK, and which also may specify a destination color profile). The bitmap graphics context specifies whether the bitmap should contain an alpha channel, and how the bitmap is generated. Functions by Task Creating Bitmap Contexts CGBitmapContextCreate (page 16) Creates a bitmap graphics context. CGBitmapContextCreateImage (page 17) Creates an image that is a copy of a bitmap graphics context. Getting Information About Bitmap Contexts These functions return the values of attributes specified when a bitmap context is created. Introduction 15 2006-05-23 | © 2006 Apple Computer, Inc. All Rights Reserved. CHAPTER 1 CGBitmapContext Reference CGBitmapContextGetBitmapInfo (page 18) Obtains the bitmap information associated with a bitmap graphics context. CGBitmapContextGetAlphaInfo (page 18) Returns the alpha information associated with the context, which indicates how a bitmap context handles the alpha component. CGBitmapContextGetBitsPerComponent