Apple Game Sprockets Guide © Apple Computer, Inc. 1996 Apple Computer, Inc. FrameMaker is a registered © 1996 Apple Computer, Inc. trademark of Frame Technology All rights reserved. Corporation. No part of this publication may be Helvetica and Palatino are reproduced, stored in a retrieval registered trademarks of system, or transmitted, in any form Linotype-Hell AG and/or its or by any means, mechanical, subsidiaries. electronic, photocopying, recording, ITC Zapf Dingbats is a registered or otherwise, without prior written trademark of International Typeface permission of Apple Computer, Inc., Corporation. except to make a backup copy of QuickView™ is licensed from Altura any documentation provided on Software, Inc. CD-ROM. Simultaneously published in the The Apple logo is a trademark of United States and Canada. Apple Computer, Inc. Use of the “keyboard” Apple logo (Option-Shift-K) for commercial Even though Apple has reviewed this purposes without the prior written manual, APPLE MAKES NO consent of Apple may constitute WARRANTY OR REPRESENTATION, trademark infringement and unfair EITHER EXPRESS OR IMPLIED, WITH competition in violation of federal RESPECT TO THIS MANUAL, ITS and state laws. QUALITY, ACCURACY, No licenses, express or implied, are MERCHANTABILITY, OR FITNESS granted with respect to any of the FOR A PARTICULAR PURPOSE. AS A technology described in this book. RESULT, THIS MANUAL IS SOLD “AS Apple retains all intellectual IS,” AND YOU, THE PURCHASER, property rights associated with the ARE ASSUMING THE ENTIRE RISK technology described in this book. AS TO ITS QUALITY AND This book is intended to assist ACCURACY. application developers to develop IN NO EVENT WILL APPLE BE applications only for Apple-labeled LIABLE FOR DIRECT, INDIRECT, or Apple-licensed computers. SPECIAL, INCIDENTAL, OR Every effort has been made to CONSEQUENTIAL DAMAGES ensure that the information in this RESULTING FROM ANY DEFECT OR manual is accurate. Apple is not INACCURACY IN THIS MANUAL, responsible for typographical errors. even if advised of the possibility of such Apple Computer, Inc. damages. 1 Infinite Loop THE WARRANTY AND REMEDIES Cupertino, CA 95014 SET FORTH ABOVE ARE EXCLUSIVE 408-996-1010 AND IN LIEU OF ALL OTHERS, ORAL Apple, the Apple logo, QuickDraw, OR WRITTEN, EXPRESS OR IMPLIED. QuickDraw GX, Mac, and No Apple dealer, agent, or employee is Macintosh are trademarks of Apple authorized to make any modification, Computer, Inc., registered in the extension, or addition to this warranty. United States and other countries. Some states do not allow the exclusion Adobe, Acrobat, Adobe Illustrator, or limitation of implied warranties or and PostScript are trademarks of liability for incidental or consequential Adobe Systems Incorporated or its damages, so the above limitation or subsidiaries and may be registered exclusion may not apply to you. This in certain jurisdictions. warranty gives you specific legal rights, and you may also have other rights which vary from state to state. Contents Figures and Listings xi Preface About This Book xiii SoundSprocket Overview xiv DrawSprocket Overview xiv InputSprocket Overview xv NetSprocket Overview xvi Format of a Typical Chapter xvi Conventions Used in This Book xvii Special Fonts xvii Types of Notes xvii Development Environment xviii For More Information xviii Chapter 1 SoundSprocket 1-1 About SoundSprocket 1-5 The Virtual Audio Environment 1-8 Listeners 1-9 Sound Sources 1-10 Optimizing Sound and Performance 1-13 Experiencing Game Sound Via Speakers and Headphones 1-14 Using SoundSprocket 1-15 Configuring Sound Output Devices 1-15 Installing the Localization Component 1-16 Controlling Filters 1-18 Accessing Version Information 1-18 Changing Localization Parameters 1-18 Determining CPU Load Steps 1-19 Changing Speaker Configurations 1-19 Creating Listeners and Sound Sources 1-20 Updating the Virtual Audio Environment 1-21 iii Using the Low-Level Interfaces 1-23 SoundSprocket Reference 1-24 Constants 1-25 Component Types and Subtypes 1-25 Sound Channel Information Selectors 1-25 Speaker Types 1-27 Sound Media 1-28 Source Modes 1-28 Data Structures 1-29 Filter Version Structure 1-29 Sound Component Link Structure 1-30 3D Sound Setup Structure 1-31 Source Location Structure 1-31 Virtual Source Structure 1-33 3D Sound Information Structure 1-33 SoundSprocket Functions 1-36 Controlling Sound Output Devices 1-36 Creating and Managing Listeners 1-37 Creating and Managing 3D Sound Sources 1-52 Sound Manager Functions 1-72 Getting and Setting Sound Channel Information 1-72 Summary of SoundSprocket 1-74 Constants 1-74 Data Types 1-75 SoundSprocket Functions 1-77 Sound Manager Functions 1-81 Result Codes 1-81 Chapter 2 DrawSprocket 2-1 About DrawSprocket 2-5 Display Configuration 2-6 Contexts and the Play State 2-7 Page Flipping and Software Buffering 2-7 How Triple Buffering Works 2-8 Gamma Fading 2-9 Underlays, Overlays, and Transparency Masks 2-10 iv Pixel Scaling 2-11 Other Features 2-11 Video Driver Support 2-12 Using DrawSprocket 2-12 Choosing a Context 2-12 Initializing the Context Attributes Structure 2-13 Finding a Context 2-14 Reserving and Activating a Context 2-15 Creating Underlays and Overlays 2-16 How Underlays Work 2-16 How Overlays Work 2-17 Fading the Display 2-17 Double-Buffered Drawing 2-18 Improving Performance With Dirty Rectangles 2-20 Cleaning Up Before Quitting DrawSprocket 2-21 Debugging 2-22 DrawSprocket Reference 2-22 Constants 2-22 Depth Masks 2-22 Color Needs 2-23 Special Display Features 2-24 Buffer Kind 2-24 Pixel Scaling 2-25 Play State 2-25 Data Structures 2-27 Context Attributes Structure 2-27 DrawSprocket Functions 2-29 Using DrawSprocket 2-29 Choosing a Context and Saving Preferences 2-31 Manipulating a Context 2-40 Drawing and Double Buffering 2-45 Using Alternate Buffers 2-59 Handling a Mouse 2-67 Manipulating Color Lookup Tables 2-70 Processing System Events 2-72 Utility Functions 2-73 Application-Defined Functions 2-75 Summary of DrawSprocket 2-77 v Constants 2-77 Data Types 2-79 DrawSprocket Functions 2-79 Application-Defined Functions 2-84 Result Codes 2-84 Chapter 3 InputSprocket 3-1 About InputSprocket 3-5 Elements 3-6 Device Configuration 3-7 Game Configuration 3-8 Obtaining Data During Play 3-9 Using InputSprocket 3-9 Initializing Need Structures and Allocating Virtual Elements 3-10 Building an Element List 3-12 Processing Input Data During Play 3-13 Turning the Keyboard and Mouse On and Off 3-16 InputSprocket Reference 3-17 Constants 3-17 Built-in Device Categories 3-18 Built-in Element Kinds 3-18 Built-in Element Labels 3-19 Button Element Data Information 3-21 Directional Pad Element Data Information 3-21 Axis Element Data Information 3-22 Need Flags 3-23 Virtual Element Flag 3-23 Element List Flag 3-23 Resource Types 3-24 Data Structures 3-24 Device Definition Structure 3-24 Element Information Structure 3-25 Button Configuration Information Structure 3-26 Directional Pad Configuration Information Structure 3-26 Axis Configuration Information Structure 3-27 Movement Data Structure 3-27 vi Element Event Data Structure 3-28 Need Structure 3-29 InputSprocket Functions 3-30 Configuring the Application 3-30 Obtaining Data From Elements 3-46 Managing Element Lists 3-51 Resources 3-58 The InputSprocket Set Resource 3-58 The InputSprocket Set List Resource 3-58 Summary of InputSprocket 3-60 Constants 3-60 Data Types 3-62 InputSprocket Functions 3-65 Result Codes 3-68 Chapter 4 NetSprocket 4-1 About NetSprocket 4-5 Players, Groups and Messages 4-6 Players 4-6 Groups 4-6 Messages 4-7 Key Features of NetSprocket 4-8 High Level Network Interface 4-9 Multiple Protocol Support 4-9 Fault-tolerance 4-9 Client/Server Topology 4-9 Network Efficiency and Speed 4-10 Human Interface Elements 4-10 Using NetSprocket 4-12 Initializing NetSprocket 4-13 Hosting a Game 4-13 Creating a Protocol Reference and Advertising Your Game 4-13 Creating a Protocol List 4-15 Adding Protocols to the Protocol List 4-15 Presenting the Host Dialog Box 4-16 Using the Host Function 4-16 vii Disposing of the Protocol List 4-17 Joining A Game 4-17 Receiving Messages From Other Players 4-18 Sending Messages to Other Players 4-19 Ending The Game 4-19 NetSprocket Reference 4-20 Constants 4-20 Network Message Priority Flags 4-20 Network Message Delivery Flags 4-21 Options for Hosting, Joining, and Deleting Games 4-22 Network Message Types 4-23 Reserved Player IDs for Network Messages 4-24 Topology Types 4-25 Data Structures 4-25 Game Reference 4-25 Protocol Reference 4-25 Protocol List Reference 4-26 Address Reference 4-26 Player Information Structure 4-27 Player Enumeration Structure 4-27 Group Information Structure 4-28 Group Enumeration Structure 4-28 Game Information Structure 4-29 Message Header Structure 4-30 Error Message Structure 4-31 Join Request Message Structure 4-32 Join Approved Message Structure 4-32 Join Denied Message Structure 4-33 Player Joined Message Structure 4-33 Player Left Message Structure 4-34 Host Changed Message Structure 4-34 Game Terminated Message Structure 4-35 NetSprocket Functions 4-35 Initializing NetSprocket 4-35 Human Interface Functions 4-39 Hosting and Joining a Game 4-42 Sending and Receiving Messages 4-49 Managing Network Protocols 4-54 viii Managing Player Information 4-62 Managing Groups of Players 4-66 Utility Functions 4-71 Summary of NetSprocket 4-75 Constants 4-75 Data Types 4-76 NetSprocket Functions 4-80 Result Codes 4-85 Glossary GL-1 Index IN-1 ix Figures and Listings Chapter 1 SoundSprocket 1-1 Figure 1-1 The position of the localization component 1-7