QuickDraw 3D Technical Reference 3D Graphics Programming With QuickDraw 3D 1.5.4 Including 3D Metafile Reference and Renderer Acceleration Virtual Engine Apple Technical Publications © Apple Computer, Inc. 1997 Apple Computer, Inc. Apple, the Apple logo, APDA, Even though Apple has reviewed this © 1997 Apple Computer, Inc. HyperCard, LaserWriter, Macintosh, manual, APPLE MAKES NO WARRANTY All rights reserved. Macintosh Quadra, MPW, and OR REPRESENTATION, EITHER EXPRESS OR IMPLIED, WITH RESPECT TO THIS No part of this publication may be PowerBook are trademarks of Apple MANUAL, ITS QUALITY, ACCURACY, reproduced, stored in a retrieval system, Computer, Inc., registered in the United MERCHANTABILITY, OR FITNESS FOR A or transmitted, in any form or by any States and other countries. PARTICULAR PURPOSE. AS A RESULT, means, mechanical, electronic, QuickDraw, QuickDraw 3D, and THIS MANUAL IS SOLD “AS IS,” AND photocopying, recording, or otherwise, QuickTime are trademarks of Apple YOU, THE PURCHASER, ARE ASSUMING without prior written permission of Computer, Inc. THE ENTIRE RISK AS TO ITS QUALITY Apple Computer, Inc., except to make a Adobe Illustrator and PostScript are AND ACCURACY. backup copy of any documentation trademarks of Adobe Systems provided on CD-ROM. Incorporated, which may be registered IN NO EVENT WILL APPLE BE LIABLE The Apple logo is a trademark of in certain jurisdictions. FOR DIRECT, INDIRECT, SPECIAL, Apple Computer, Inc. America Online is a registered service INCIDENTAL, OR CONSEQUENTIAL Use of the “keyboard” Apple logo mark of America Online, Inc. DAMAGES RESULTING FROM ANY DEFECT OR INACCURACY IN THIS (Option-Shift-K) for commercial CompuServe is a registered service MANUAL, even if advised of the possibility purposes without the prior written mark of CompuServe, Inc. of such damages. consent of Apple may constitute FrameMaker is a registered trademark trademark infringement and unfair of Frame Technology Corporation. THE WARRANTY AND REMEDIES SET competition in violation of federal and FORTH ABOVE ARE EXCLUSIVE AND IN Helvetica and Palatino are registered state laws. LIEU OF ALL OTHERS, ORAL OR trademarks of Linotype Company. No licenses, express or implied, are WRITTEN, EXPRESS OR IMPLIED. No granted with respect to any of the Internet is a trademark of Digital Apple dealer, agent, or employee is technology described in this book. Equipment Corporation. authorized to make any modification, Apple retains all intellectual property ITC Zapf Dingbats is a registered extension, or addition to this warranty. rights associated with the technology trademark of International Typeface Some states do not allow the exclusion or described in this book. This book is Corporation. limitation of implied warranties or liability intended to assist application Optrotech is a trademark of Orbotech for incidental or consequential damages, so developers to develop applications only Corporation. the above limitation or exclusion may not for Apple-labeled or Apple-licensed Silicon Graphics is a registered apply to you. This warranty gives you computers. trademark and OpenGL is a trademark specific legal rights, and you may also have Every effort has been made to ensure of Silicon Graphics, Inc. other rights which vary from state to state. that the information in this manual is UNIX is a registered trademark of accurate. Apple is not responsible for Novell, Inc. in the United States and typographical errors. other countries, licensed exclusively Apple Computer, Inc. through X/Open Company, Ltd. 1 Infinite Loop X Window System is a trademark of the Cupertino, CA 95014 Massachusetts Institute of Technology. 408-996-1010 Simultaneously published in the United States and Canada. Contents Figures, Tables, and Listings 27 Preface About This Document 35 Companion Documents 37 Format of a Typical Chapter 37 Conventions Used in This Document 38 Special Fonts 38 Types of Notes 38 Development Environment 39 For More Information 39 Chapter 1 Introduction to QuickDraw 3D 41 About QuickDraw 3D 41 Modeling and Rendering 42 Interacting 43 Extending QuickDraw 3D 44 Naming Conventions 47 Constants 47 Data Types 48 Functions 49 Retained and Immediate Modes 50 Using QuickDraw 3D 52 Compiling Your Application 53 Initializing and Terminating QuickDraw 3D 54 Creating a Model 56 Configuring a Window 59 Creating Lights 62 Creating a Draw Context 65 Creating a Camera 66 Creating a View 67 Rendering a Model 69 3 QuickDraw 3D Reference 71 Constants 71 Gestalt Selectors and Response Values 71 Boolean Values 72 Status Values 72 Coordinate Axes 73 QuickDraw 3D Routines 73 Initializing and Terminating QuickDraw 3D 73 Getting Version Information 75 Managing Sets 76 Managing Shapes 81 Managing Strings 83 QuickDraw 3D Errors, Warnings, and Notices 87 Chapter 2 3D Viewer 91 About the 3D Viewer 92 Controller Strips 94 Badges 95 Drag and Drop 97 Using the 3D Viewer 99 Checking for the 3D Viewer 99 Checking the Version of the 3D Viewer 100 Creating a Viewer 101 Attaching Data to a Viewer 102 Handling Viewer Events 103 3D Viewer Reference 104 Constants 104 Gestalt Selector and Response Values 104 Viewer Flags 105 Viewer State Flags 108 Camera View Commands 108 3D Viewer Routines 110 Creating and Destroying Viewers 110 Attaching Data to a Viewer 112 Drawing a Viewer and its Contents 114 Managing Viewer Information and State 118 4 Updating Viewer Data 142 Handling Viewer Events 145 Managing Cursors 150 Handling Edit Commands 153 Windows-Specific API 157 Window and Clipboard Definitions 157 WM_NOTIFY Data Structures 157 WM_NOTIFY Definitions 158 Functions 158 Application-Defined Routine 160 Chapter 3 QuickDraw 3D Objects 163 About QuickDraw 3D Objects 163 The QuickDraw 3D Class Hierarchy 164 QuickDraw 3D Objects 166 QuickDraw 3D Object Subclasses 167 Shared Object Subclasses 168 Set Object Subclasses 169 Shape Object Subclasses 170 Group Object Subclasses 171 Shader Object Subclasses 171 Reference Counts 171 Using QuickDraw 3D Objects 175 Determining the Type of a QuickDraw 3D Object 175 Defining an Object Metahandler 176 How Your Metahandler is Called 177 Defining Custom Elements 177 QuickDraw 3D Objects Reference 178 QuickDraw 3D Objects Routines 178 Managing Objects 178 Determining Object Types 181 Analyzing the Object Hierarchy 184 Managing Shared Objects 189 Extending Shapes and Sets 193 Creating Custom Object Subclasses 194 Custom Class Metahandlers 196 5 Object Types and Names 198 Data Structures Associated With a Class 201 Registering a Custom Class 202 Registering a Shared Library 207 Creating a Hierarchy 211 Object Methods 213 Multilevel Methods 213 Class Routines 214 Instantiating an Object 215 Accessing Types in a Class 216 Version Checking 218 Class Method Retrieval 219 Accessing Private Data 221 Class Methods 223 Class Registration and Unregistration 224 Class Version 228 Object Creation and Deletion 229 Shared Objects 232 I/O Methods 233 Object Errors, Warnings, and Notices 234 Chapter 4 Geometric Objects 237 About Geometric Objects 237 Attributes of Geometric Objects 239 Polyhedral Primitives 240 Meshes 240 Trigrids 244 Polyhedra 245 Trimeshes 246 Comparison of the Polyhedral Primitives 247 NURB Curves and Patches 248 Surface Parameterizations 252 Using Geometric Objects 257 Creating and Deleting Geometric Objects 257 Using Polyhedrons 258 Creating a Polyhedron 259 6 Using Trimeshes 267 Using Meshes 269 Creating a Mesh 270 Traversing a Mesh 272 Using Trigrids 274 Geometric Objects Reference 275 Constants 275 Geometric Object Types 275 Pixel Types 277 Endian Types 279 General Polygon Shape Hints 279 End Caps Masks 280 Polyhedron Edge Masks 281 Data Structures 282 Points 283 Rational Points 284 Polar and Spherical Points 284 Vectors 286 Quaternions 287 Rays 288 Parametric Points 288 Tangents 289 Vertices 289 Matrices 290 Bitmaps and Pixel Maps 291 Areas and Plane Equations 294 Point Objects 295 Lines 295 Polylines 296 Triangles 297 Simple Polygons 298 General Polygons 299 Boxes 301 Trigrids 304 Meshes 305 Trimeshes 307 Polyhedra 311 Ellipses 314 7 NURB Curves 315 NURB Patches 317 Ellipsoids 320 Cylinders 322 Disks 323 Cones 325 Tori 326 Markers 329 Geometric Objects Routines 331 Managing Geometric Objects 331 Creating and Editing Points 334 Creating and Editing Lines 337 Creating and Editing Polylines 342 Creating and Editing Triangles 349 Creating and Editing Simple Polygons 354 Creating and Editing General Polygons 360 Creating and Editing Boxes 367 Creating and Editing Trigrids 375 Creating and Editing Meshes 382 Traversing Mesh Components, Vertices, Faces, and Edges 410 Creating and Editing Trimeshes 430 Creating and Editing Polyhedra 432 Creating and Editing Ellipses 440 Creating and Editing NURB Curves 446 Creating and Editing NURB Patches 451 Creating and Editing Ellipsoids 458 Creating and Editing Cylinders 465 Creating and Editing Disks 476 Creating and Editing Cones 482 Creating and Editing Tori 491 Creating and Editing Bitmap Markers 499 Creating and Editing Pixmap Markers 505 Managing Bitmaps 512 Geometry Errors, Warnings, and Notices 513 8 Chapter 5 Attribute Objects 515 About Attribute Objects 515 Types of Attributes and Attribute Sets 516 Attribute Inheritance 518 Using Attribute Objects 520 Creating and Configuring Attribute Sets 520 Iterating Through an Attribute Set 521 Defining Custom Attribute Types 522 Attribute Objects Reference 526 Constants 526 Attribute Types 527 Attribute Objects Routines 529 Drawing Attributes 529 Creating and Managing Attribute Sets 530 Registering Custom Attributes 535 Adding Application-Defined Attribute and Element