Inside QuickTime The QuickTime Technical Reference Library Interactive Movies October 2002 Apple Computer, Inc. Java and all Java-based trademarks © 2001 Apple Computer, Inc. are trademarks of Sun Microsystems, All rights reserved. Inc. in the U.S. and other countries. No part of this publication may be Simultaneously published in the reproduced, stored in a retrieval United States and Canada system, or transmitted, in any form or Even though Apple has reviewed this by any means, mechanical, electronic, manual, APPLE MAKES NO photocopying, recording, or WARRANTY OR REPRESENTATION, otherwise, without prior written EITHER EXPRESS OR IMPLIED, WITH permission of Apple Computer, Inc., RESPECT TO THIS MANUAL, ITS with the following exceptions: Any QUALITY, ACCURACY, person is hereby authorized to store MERCHANTABILITY, OR FITNESS documentation on a single computer FOR A PARTICULAR PURPOSE. AS A for personal use only and to print RESULT, THIS MANUAL IS SOLD “AS copies of documentation for personal IS,” AND YOU, THE PURCHASER, ARE use provided that the documentation ASSUMING THE ENTIRE RISK AS TO contains Apple’s copyright notice. ITS QUALITY AND ACCURACY. The Apple logo is a trademark of IN NO EVENT WILL APPLE BE LIABLE Apple Computer, Inc. FOR DIRECT, INDIRECT, SPECIAL, Use of the “keyboard” Apple logo INCIDENTAL, OR CONSEQUENTIAL (Option-Shift-K) for commercial DAMAGES RESULTING FROM ANY purposes without the prior written DEFECT OR INACCURACY IN THIS consent of Apple may constitute MANUAL, even if advised of the trademark infringement and unfair possibility of such damages. competition in violation of federal and state laws. THE WARRANTY AND REMEDIES SET FORTH ABOVE ARE EXCLUSIVE AND No licenses, express or implied, are IN LIEU OF ALL OTHERS, ORAL OR granted with respect to any of the WRITTEN, EXPRESS OR IMPLIED. No technology described in this book. Apple dealer, agent, or employee is Apple retains all intellectual property authorized to make any modification, rights associated with the technology extension, or addition to this warranty. described in this book. This book is intended to assist application Some states do not allow the exclusion or developers to develop applications limitation of implied warranties or only for Apple-labeled or liability for incidental or consequential Apple-licensed computers damages, so the above limitation or Every effort has been made to ensure exclusion may not apply to you. This that the information in this document warranty gives you specific legal rights, is accurate. Apple is not responsible and you may also have other rights which for typographical errors. vary from state to state. Apple Computer, Inc. 1 Infinite Loop Cupertino, CA 95014 408-996-1010 Apple, the Apple logo, AppleScript, ColorSync, Mac, Macintosh, QuickDraw, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries. Aqua is a trademark of Apple Computer, Inc. Contents Preface About This Book 15 Book Structure 15 Conventions Used in This Book 17 Special Fonts 17 Types of Notes 17 Development Environment 18 Updates to This Book 18 For More Information 18 Chapter 1 QuickTime Interactivity 21 QuickTime Basics 23 Movies and Media Data Structures 23 Movies––A Few Good Concepts 25 Time Management 26 The QuickTime Architecture 27 The Movie Toolbox 27 The Image Compression Manager 28 QuickTime Components 28 The Component Manager 30 Atoms 30 QuickTime Player 31 Sprites and Sprite Animation 35 Creating Desktop Sprites 37 Wired Movies 40 Adding Actions 40 Wired Actions 41 User Events 42 Using Flash and QuickTime 43 QuickTime Media Skins 45 QuickTime VR 49 The QuickTime VR Media Type 50 3 Apple Computer, Inc. October 2002 CONTENTS Creating QTVR Movies Programmatically 52 Chapter 2 QuickTime Sprites, Sprite Animation and Wired Movies 55 Sprite Animation and the Sprite Toolbox 56 Sprites and the Sprite Toolbox 56 Sprite World Characteristics 57 Sprite Tracks 58 Sprite Animation 59 Sprite Spatial Concepts 59 Local Coordinate System 60 Source Box 60 Bounding Box 61 Four Corners 62 Registration Point 62 Display Space 68 Sprite Properties 69 Wired Movies 70 Adding Actions 70 QuickTime Events 71 Actions and Their Targets 71 Action Parameters 72 Expressions 73 Operators 73 Operands 74 External Movie Targets for Wired Actions 74 Chapter 3 Sprite Media Handler 75 Defining the Sprite Media Handler 76 Key Frame Samples and Override Samples 77 Sprite Track Media Format 78 Assigning Group IDs 81 Sprite Image Registration 82 Sprite Track Properties 83 Alternate Sources for Sprite Image Data 84 4 Apple Computer, Inc. October 2002 CONTENTS Supported Modifier Inputs 85 Hit-Testing Flags 85 Using Sprites in a Sprite Track 86 Referenced Sprite Images 86 Specifying Sprite Button Behaviors 86 Using the Action Handler Sprite Property 87 String Variable Support 88 Creating a QuickTime Sprite Movie 88 Useful Sprite Media Handler Functions 97 SpriteMediaSetSpriteProperty 97 SpriteMediaGetSpriteProperty 98 SpriteMediaHitTestAllSprites 99 SpriteMediaCountSprites 99 SpriteMediaCountImages 100 SpriteMediaGetIndImageDescription 100 SpriteMediaGetDisplayedSampleNumber 100 SpriteMediaGetSpriteName 101 SpriteMediaGetImageName 101 SpriteMediaHitTestOneSprite 101 SpriteMediaSpriteIndexToID 101 SpriteMediaSpriteIDToIndex 102 SpriteMediaGetIndImageProperty 102 Sprites Functions Specific to Wired Sprites 102 SpriteMediaSetActionVariable 102 SpriteMediaGetActionVariable 102 SpriteDescription Structure 103 Wired Actions in QuickTime 5 103 New Wired Actions 103 New Wired Operands 109 Chapter 4 Authoring Wired Movies and Sprite Animations 115 Authoring Movies With the Sprite Media Handler 116 Defining a Key Frame Sample 116 Creating the Movie, Sprite Track, and Media 117 Adding Images to the Key Frame Sample 118 Adding More Images for Other Sprites 119 5 Apple Computer, Inc. October 2002 CONTENTS Adding Sprites to the Key Frame Sample 120 Adding More Actions to Other Sprites 124 Adding Sample Data in Compressed Form 125 Defining Override Samples 125 Setting Properties of the Sprite Track 127 Retrieving Sprite Data From a Modifier Track 128 Authoring Wired Movies 132 Actions of the First Penguin 134 Actions of the Second Penguin 134 Creating a Wired Sprite Movie 134 Assigning the No Controller to the Movie 135 Setting Up the Sprite Track’s Properities 135 Adding an Event Handler to the Penguin 137 Adding a Series of Actions to the Penguins 137 Important Things to Note in the Sample Code 139 Authoring Movies With External Movie Targets 140 Specifying an External Movie Target for an Action 140 Target Atoms for Embedded Movies 141 Supporting External Movie Targets 142 Specifying String Parameters to Actions and Operands 142 Wiring a Movie by Adding an HREF Track 144 Creating an HREF Track 145 Adding Hypertext Links to a QuickTime Movie With a Text Track 146 Step #1––Creating a Movie With a Text Track and Hypertext Links 146 Step #2––Creating a New Text Movie 147 Step #3––Adding a Text Sample to the Movie 148 Step #4––Adding a Hypertext Link 150 Step #5––Adding a Specified Atom Container 153 Step #6––Getting the First Media Sample 155 Step #7––Adding Hypertext Actions 156 Step #8––Replacing the Sample 156 Step #9––Updating the Movie Resource 157 Chapter 5 Using the Sprite Toolbox to Create Sprite Animations 159 Overview of Sprite Toolbox 159 How To Add Sprite-Based Animations to an Application 160 6 Apple Computer, Inc. October 2002 CONTENTS Creating and Initializing a Sprite World 160 Creating and Initializing Sprites 162 Creating Sprites for a Sample Application 163 Animating Sprites 165 Disposing of a Sprite Animation 168 Sprite Hit-Testing 169 Hit-Testing Flags 169 Enhancing Sprite Animation Performance 170 Constants and Functions in the Sprite Toolbox 170 Constants 171 Background Sprites 171 Flags for Sprite Hit-Testing 171 Sprite Properties 172 Flags for SpriteWorldIdle 173 Sprite and Sprite World Identifiers 173 Useful Sprite Toolbox Functions 174 NewSpriteWorld 174 DisposeSpriteWorld 175 SetSpriteWorldClip 175 SetSpriteWorldMatrix 175 SpriteWorldIdle 176 InvalidateSpriteWorld 176 SpriteWorldHitTest 176 DisposeAllSprites 177 NewSprite 177 DisposeSprite 177 InvalidateSprite 177 SpriteHitTest 178 GetSpriteProperty 178 SetSpriteProperty 179 Chapter 6 Flash Media Handler 181 Flash Media 182 Flash Support in QuickTime 5 183 Wired Actions and Operands 184 kActionFlashTrackSetFlashVariable 184 7 Apple Computer, Inc. October 2002 CONTENTS kActionFlashTrackDoButtonActions 185 kOperandFlashTrackVariable 185 QT Events 185 Importing a Flash Movie 186 Adding Wired Actions To a Flash Track 187 Extending the SWF Format 187 What You Need to Modify 188 Chapter 7 Creating Advanced Interactive Movies 191 Embedded Movies 191 Creating New Types of QuickTime Movies 191 Using Embedded Movies 192 Dynamically Loading Embedded Movies From URLs 193 Triggering Wired Actions When an Embedded Movie is Loaded 194 Targeting Elements of Embedded Movies with All Wired Actions 194 Target Type Atoms for Hierarchical Movies 196 Example #1 197 Example #2 198 Movie Track and Movie Wired Actions 198 Movie Controller Actions 199 Wired QT Event 200 Extended Wired Operand Functionality 201 Wired Actions and JavaScript 201 Movie Property Atom Toolbox Routines 202 Custom Wired Actions 202 Custom Action Handler Usage 203 Authoring Custom Wired Actions 204 Extension to Wired Movie Format: Executing Custom Actions 204 Wired Actions 204 Wired Operands 205 Writing a Custom Action Handler Component 205 The Action Being Executed 207 Fetching the Parameters 207 8 Apple