INSIDE MACINTOSH Imaging With QuickDraw Apple Computer, Inc. CompuServe is a registered service LIMITED WARRANTY ON MEDIA AND © 1994 Apple Computer, Inc. mark of CompuServe, Inc. REPLACEMENT All rights reserved. FrameMaker is a registered trademark ALL IMPLIED WARRANTIES ON THIS No part of this publication may be of Frame Technology Corporation. MANUAL, INCLUDING IMPLIED reproduced, stored in a retrieval system, Helvetica and Palatino are registered WARRANTIES OF MERCHANTABILITY or transmitted, in any form or by any trademarks of Linotype Company. AND FITNESS FOR A PARTICULAR means, mechanical, electronic, Internet is a trademark of Digital PURPOSE, ARE LIMITED IN DURATION photocopying, recording, or otherwise, Equipment Corporation. TO NINETY (90) DAYS FROM THE DATE without prior written permission of OF THE ORIGINAL RETAIL PURCHASE ITC Zapf Dingbats is a registered Apple Computer, Inc. Printed in the OF THIS PRODUCT. trademark of International Typeface United States of America. Corporation. Even though Apple has reviewed this No licenses, express or implied, are MacPaint is a registered trademark of manual, APPLE MAKES NO WARRANTY granted with respect to any of the Claris Corporation. OR REPRESENTATION, EITHER EXPRESS technology described in this book. OR IMPLIED, WITH RESPECT TO THIS NuBus is a trademark of Texas Apple retains all intellectual property MANUAL, ITS QUALITY, ACCURACY, Instruments. rights associated with the technology MERCHANTABILITY, OR FITNESS FOR A described in this book. This book is Motorola is a registered trademark of PARTICULAR PURPOSE. AS A RESULT, intended to assist application Motorola Corporation. THIS MANUAL IS SOLD “AS IS,” AND developers to develop applications only Optrotech is a trademark of Orbotech YOU, THE PURCHASER, ARE ASSUMING for Apple Macintosh computers. Corporation. THE ENTIRE RISK AS TO ITS QUALITY Every effort has been made to ensure Simultaneously published in the United AND ACCURACY. that the information in this manual is States and Canada. IN NO EVENT WILL APPLE BE LIABLE accurate. Apple is not responsible for FOR DIRECT, INDIRECT, SPECIAL, printing or clerical errors. INCIDENTAL, OR CONSEQUENTIAL Apple Computer, Inc. DAMAGES RESULTING FROM ANY 20525 Mariani Avenue DEFECT OR INACCURACY IN THIS Cupertino, CA 95014 MANUAL, even if advised of the possibility 408-996-1010 of such damages. Apple, the Apple logo, APDA, THE WARRANTY AND REMEDIES SET AppleLink, AppleTalk, ImageWriter, FORTH ABOVE ARE EXCLUSIVE AND IN LaserWriter, Macintosh, MPW, LIEU OF ALL OTHERS, ORAL OR PowerBook, and StyleWriter are WRITTEN, EXPRESS OR IMPLIED. No trademarks of Apple Computer, Inc., Apple dealer, agent, or employee is registered in the United States and other authorized to make any modification, countries. extension, or addition to this warranty. ColorSync, Finder, Geneva, QuickDraw, Some states do not allow the exclusion or QuickTime, ResEdit, System 7, and limitation of implied warranties or liability TrueType are trademarks of Apple for incidental or consequential damages, so Computer, Inc. the above limitation or exclusion may not Adobe Illustrator, Adobe Photoshop, apply to you. This warranty gives you and PostScript are trademarks of Adobe specific legal rights, and you may also have Systems Incorporated, which may be other rights which vary from state to state. registered in certain jurisdictions. America Online is a service mark of Quantum Computer Services, Inc. Classic is a registered trademark licensed to Apple Computer, Inc. Contents Figures, Tables, and Listings xiii Preface About This Book xxi Format of a Typical Chapter xxii Conventions Used in This Book xxiii Special Fonts xxiii Types of Notes xxiii Empty Strings xxiv Assembly-Language Information xxiv The Development Environment xxiv Chapter 1 Introduction to QuickDraw 1-1 Drawing Environments 1-4 QuickDraw’s Coordinate Plane 1-6 Images 1-10 Colors 1-17 Indexed Colors 1-19 Direct Colors 1-20 Multiple Screens 1-21 From Memory Bits to Onscreen Pixels 1-24 From Memory Bits to Printers 1-26 Other Graphics Managers 1-28 Chapter 2 Basic QuickDraw 2-1 About Basic QuickDraw 2-3 The Mathematical Foundations of QuickDraw 2-4 The Coordinate Plane 2-4 Points 2-4 Rectangles 2-5 Regions 2-7 The Black-and-White Drawing Environment: Basic Graphics Ports 2-7 Bitmaps 2-9 The Graphics Port Drawing Area 2-11 Graphics Port Bit Patterns 2-13 The Graphics Pen 2-13 Text in a Graphics Port 2-13 iii The Limited Colors of a Basic Graphics Port 2-14 Other Fields 2-14 Using Basic QuickDraw 2-14 Initializing Basic QuickDraw 2-16 Creating Basic Graphics Ports 2-16 Setting the Graphics Port 2-18 Switching Between Global and Local Coordinate Systems 2-19 Scrolling the Pixels in the Port Rectangle 2-20 Basic QuickDraw Reference 2-26 Data Structures 2-26 Routines 2-36 Initializing QuickDraw 2-36 Opening and Closing Basic Graphics Ports 2-37 Saving and Restoring Graphics Ports 2-41 Managing Bitmaps, Port Rectangles, and Clipping Regions 2-43 Manipulating Points in Graphics Ports 2-51 Summary of Basic QuickDraw 2-56 Pascal Summary 2-56 Data Types 2-56 Routines 2-57 C Summary 2-58 Data Types 2-58 Functions 2-60 Assembly-Language Summary 2-61 Data Structures 2-61 Global Variables 2-62 Result Codes 2-62 Chapter 3 QuickDraw Drawing 3-1 About QuickDraw Drawing 3-3 The Graphics Pen 3-4 Bit Patterns 3-5 Boolean Transfer Modes With 1-Bit Pixels 3-8 Lines and Shapes 3-11 Defining Lines and Shapes 3-11 Framing Shapes 3-12 Painting and Filling Shapes 3-12 Erasing Shapes 3-12 Inverting Shapes 3-13 Other Graphic Entities 3-13 The Eight Basic QuickDraw Colors 3-14 Drawing With QuickDraw 3-16 Drawing Lines 3-17 Drawing Rectangles 3-22 iv Drawing Ovals, Arcs, and Wedges 3-25 Drawing Regions and Polygons 3-27 Performing Calculations and Other Manipulations of Shapes 3-31 Copying Bits Between Graphics Ports 3-32 Customizing QuickDraw’s Low-Level Routines 3-35 QuickDraw Drawing Reference 3-36 Data Structures 3-36 Routines 3-41 Managing the Graphics Pen 3-41 Changing the Background Bit Pattern 3-48 Drawing Lines 3-49 Creating and Managing Rectangles 3-52 Drawing Rectangles 3-58 Drawing Rounded Rectangles 3-63 Drawing Ovals 3-68 Drawing Arcs and Wedges 3-71 Creating and Managing Polygons 3-78 Drawing Polygons 3-81 Creating and Managing Regions 3-85 Drawing Regions 3-100 Scaling and Mapping Points, Rectangles, Polygons, and Regions 3-104 Calculating Black-and-White Fills 3-108 Copying Images 3-112 Drawing With the Eight-Color System 3-122 Determining Whether QuickDraw Has Finished Drawing 3-125 Getting Pattern Resources 3-126 Customizing QuickDraw Operations 3-129 Resources 3-140 The Pattern Resource 3-140 The Pattern List Resource 3-141 Summary of QuickDraw Drawing 3-142 Pascal Summary 3-142 Constants 3-142 Data Types 3-144 Routines 3-145 C Summary 3-149 Constants 3-149 Data Types 3-151 Functions 3-152 Assembly-Language Summary 3-157 Data Structures 3-157 Global Variables 3-158 v Chapter 4 Color QuickDraw 4-1 About Color QuickDraw 4-4 RGB Colors 4-4 The Color Drawing Environment: Color Graphics Ports 4-5 Pixel Maps 4-9 Pixel Patterns 4-12 Color QuickDraw’s Translation of RGB Colors to Pixel Values 4-13 Colors on Grayscale Screens 4-17 Using Color QuickDraw 4-18 Initializing Color QuickDraw 4-19 Creating Color Graphics Ports 4-20 Drawing With Different Foreground Colors 4-21 Drawing With Pixel Patterns 4-23 Copying Pixels Between Color Graphics Ports 4-26 Boolean Transfer Modes With Color Pixels 4-32 Dithering 4-37 Arithmetic Transfer Modes 4-38 Highlighting 4-41 Color QuickDraw Reference 4-44 Data Structures 4-45 Color QuickDraw Routines 4-63 Opening and Closing Color Graphics Ports 4-63 Managing a Color Graphics Pen 4-67 Changing the Background Pixel Pattern 4-68 Drawing With Color QuickDraw Colors 4-70 Determining Current Colors and Best Intermediate Colors 4-79 Calculating Color Fills 4-82 Creating, Setting, and Disposing of Pixel Maps 4-85 Creating and Disposing of Pixel Patterns 4-87 Creating and Disposing of Color Tables 4-91 Retrieving Color QuickDraw Result Codes 4-94 Customizing Color QuickDraw Operations 4-96 Reporting Data Structure Changes to QuickDraw 4-97 Application-Defined Routine 4-101 Resources 4-102 The Pixel Pattern Resource 4-103 The Color Table Resource 4-104 The Color Icon Resource 4-105 Summary of Color QuickDraw 4-107 Pascal Summary 4-107 Constants 4-107 Data Types 4-109 Color QuickDraw Routines 4-113 Application-Defined Routine 4-115 vi C Summary 4-115 Constants 4-115 Data Types 4-118 Color QuickDraw Functions 4-122 Application-Defined Function 4-124 Assembly-Language Summary 4-124 Data Structures 4-124 Result Codes 4-128 Chapter 5 Graphics Devices 5-1 About Graphics Devices 5-3 Using Graphics Devices 5-6 Optimizing Your Images for Different Graphics Devices 5-8 Zooming Windows on Multiscreen Systems 5-9 Setting a Device’s Pixel Depth 5-13 Exceptional Cases When Working With Color Devices 5-13 Graphics Devices Reference 5-14 Data Structures 5-15 Routines for Graphics Devices 5-19 Creating, Setting, and Disposing of GDevice Records 5-19 Getting the Available Graphics Devices 5-25 Determining the Characteristics of a Video Device 5-29 Changing the Pixel Depth for a Video Device 5-33 Application-Defined Routine 5-35 Resource 5-37 The Screen Resource 5-37 Summary of Graphics Devices 5-38 Pascal Summary 5-38 Constants 5-38 Data Types 5-39 Routines for Graphics Devices 5-40 Application-Defined Routine 5-40 C Summary 5-41 Constants 5-41 Data Types 5-41 Functions for Graphics Devices 5-43 Application-Defined Function 5-44 Assembly-Language Summary 5-44 Data Structure