QuickTime Toolkit
Volume One: Basic Movie Playback and Media Types Apple
AMSTERDAM * BOSTON 9HEIDELBERG ~ L O N D O N N E W Y O R K ~ O X F O R D * PARIS * SAN D I E G O SAN F R A N C I S C O * S I N G A P O R E ~ S Y D N E Y * T O K Y O
ELSEVIER
M o r g a n K a u f m a n n Publishers is an i m p r i n t o f Elsevier
MORGAN
KAUFMANN
PUBLISHERS
QuickTime Developer Series Apple's QuickTime is a way to deliver multimedia--video, sound, styled text, MIDI, Flash, virtual reality, 3D models, sprites, and more--wrapped in a package that will play on Windows or Macintosh computers, on CD-ROM, over the Internet, in a browser window, a PDF document, a PowerPoint presentation, a Word document, or all by itself. The Q u i c k T i m e D e v e l o p e r Series, developed in close cooperation with Apple, is devoted to exploring all of the capabilities of this powerful industry standard. Books in the series are written by experienced developers, including engineers from within the development team at Apple. All of the books feature a practical, hands-on approach and are prepared according to the latest developments in QuickTime technology. QuickTime Toolkit, Volume One: Basic Movie Playback and Media Types Apple Q uickTime Toolkit, Volume 7h,o: Advanced Movie Playback and Media ~pes Apple Interactive QuickTime: Authoring Wired Media Matthew Peterson QuickTime for the Web: For Windows and Macintosh, Third Edition Apple
I know a lot about O uickTime, but [the author] seems to know more: little nuggets of information that can be very valuable in the future--things you didn't even know you didn't know. I wish I had this book when I was just starting out working with Quick Time. It would have saved me a lot of time trying to figure things out on my own. --Steve Israelson VP Technology, TotallyHip Inc. Ever found yourself floundering in API documentation, samples, and developer lists when it comes to implementing one or other of the many wonderful QuickTime features? Well flounder no longer/The ever-practical QuickTime Developer Series comes to the rescue with QuickTime Toolkit: everything you need to know to get a host of Quick Time features actually working for you, presented in its customary lucid and down-to-earth style. Unquestionably the first port of call for anyone contemplating Quick Time development at the A l l level on OS X, Windows, or both, and--with chapters covering such topics as Data Handlers, Carbon Events, cross-platform issues, and error handling--an invaluable resource even for seasoned Quick Time developers. --John Cromie Skylark Associates Ltd. I just got [this] book in the mail and spent a few hours reading it . . . . Finally, good documentation on some of the Quick Time functions that have been so mysterious/ I'm going to look at that sprite override code for making panning videos . . . . [The author] has been and remains a great source of information on Quick Time. He has a uniquely proactive creative~logical approach demonstrating the great possibilities in a great technology. --Bill Meikle programmer, vrhotwires.com
Senior Editor Publishing Services Manager Project Editor Project Management Editorial Coordinator Cover Design Cover Image~Photo Series Text Design Composition Illustration Copyeditor Proofreader Indexer Interior Printer Cover Printer
Tim Cox Andr6 Cuello Anne B. McGee Elisabeth Belier Rick Camp Laurie Anderson 9 Digital Vision/Getty Images Rebecca Evans Nancy Logan Dartmouth Publishing, Inc. Yonie Overton Jennifer McClain Jay Kreider The Maple-Vail Book Manufacturing Group Phoenix Color Corporation
9 2004 by Apple Computer, Inc. All rights reserved. Apple, the Apple logo, and QuickTime are trademarks of Apple Computer, Inc., registered in the United States and other countries, used by Morgan Kaufmann under license. The QuickTime logo is a trademark of Apple Computer, Inc., used by Morgan Kaufmann under license. Designations used by companies to distinguish their products are often claimed as trademarks or registered trademarks. In all instances in which Morgan Kaufmann Publishers is aware of a claim, the product names appear in initial capital or all capital letters. Readers, however, should contact the appropriate companies for more complete information regarding trademarks and registration. Morgan Kaufmann Publishers is an imprint of Elsevier. 500 Sansome Street, Suite 400, San Francisco, CA 94111 No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means--electronic, mechanical, photocopying, scanning, or otherwise--without prior written permission of the publisher. Permissions may be sought directly from Elsevier's Science & Technology Rights Department in Oxford, UK: phone: {+ 44} 1865 843830, fax: {+ 44} 1865 853333, e-mail:
[email protected]. You may also complete your request on-line via the Elsevier homepage {http://elsevier.com} by selecting Customer Support and then Obtaining Permissions.
Library of Congress Cataloguing-in-Publication Application submitted. ISBN: 0-12-088401-1 For information on all Morgan Kaufmann publications, visit our website at www.mkp.com. Printed in the United States of America 04 05 06 07 08
5 4 3 2 1
This book is printed on acid-free paper.
Contents Preface Development Platforms How to Read This Book
XV
xvi xvii
xviii
Acknowledgements Chapter I
It All Starts Today Introduction 1 Movie Controllers 1 The Application Framework 4 Handling Movie Windows 6 Handling Menus 11 QuickTime Support 13 Opening a Movie File 13 Attaching a Movie Controller 14 Handling Events 17 Editing a Movie 18 Conclusion 20
Chapter 2
21
Control Introduction 21 Managing the Controller Bar 22 Showing and Hiding the Controller Bar 22 Using Badges 24 Attaching and Detaching the Controller Bar 25 Managing Controller Bar Buttons 28 Managing the Standard Controller Buttons 28 Managing the QuickTime VR Controller Buttons Using the Controller Bar Custom Button 32 Selecting an Entire Movie 36 Movie User Data 38 Specifying the Controller Type 39 Manipulating a Movie's Looping State 43 Getting a Movie's Stored Window Position 46
29
Contents
v
Opening URLs 48 Conclusion 50 Chapter 3
51
Out of Control
Introduction 51 Getting Started 55 Setting Up to Use QuickTime 55 Using Application-Specific Data 56 Updating the Application Framework 59 Preparing Movies for Playback 62 Prerolling Movies 62 Preprerolling Movies 63 Playing Movies 65 Editing Movies 67 Looping Movies 71 Playing Picture-in-Picture Movies 76 Setting the Picture-in-Picture Movie Geometry 76 Setting the Main Movie's Display Clipping Region 77 Playing the Picture-in-Picture Movie 79 Moving the Picture-in-Picture Movie 81 Conclusion 83 Chapter 4
Chapter 5
vi
Contents
The Image Introduction 85 Importing Images 87 Expanding the Application Framework 91 Transforming Images 95 Working with Image Matrices 96 Flipping Images 98 Rotating Images 100 Scaling Images 102 Working with Multi-image Files 105 Exporting Images 106 Exporting Images Using the Export Image Dialog Box Exporting Images Directly 109 Finding Image Files 112 Conclusion 114 In and Out Introduction
85
107
117
117
Exporting Movies 118 Converting to Any Available Export Format 120 Converting to a Specific Export Format 121 Using Movie Export Settings 123 Importing Files 127 Filtering Out Movies 127 Importing In Place 129 Importing Files 131 Default Progress Functions 133 Custom Progress Functions 134 Opening the Dialog Box 137 Handling Progress Messages 138 Handling User Actions 1,$0 Closing the Dialog Box 143 Progress Functions for Image Operations 147 The Code 149 Conclusion 149
Chapter 6
Doug's 1st Movie
151
Introduction 151 The Structure of QuickTime Movies 152 The Structure of QuickTime Movie Files 154 Double-Fork and Single-Fork Movie Files 154 Fast Start Movie Files 156 Reference and Self-Contained Movie Files 157 Interleaved and Non-interleaved Movie Files 159 Creating QuickTime Movie Files 160 Creating a New Movie File 163 Adding Tracks to a Movie 164 Adding a Media to a Track 164 Adding Samples to a Media 166 Inserting a Media Segment 167 Adding the Movie Atom 168 Finishing Up 168 Adding Media Samples 169 Drawing Video Frames 170 Compressing Video Frames 173 Adding Video Frames to a Media 176 Saving a Movie 179 The Code 179 Conclusion 181
Contents
vii
Chapter 7
183
The Informant Introduction 183 Movie Posters 186 Getting and Setting Movie Poster Times 187 Working with Movie Poster Tracks 189 Movie Previews 191 Defining Movie Previews 191 Playing Movie Previews 193 Clearing Movie Previews 194 File Previews 196 Accessing File Previews 197 Creating File Previews 198 Movie Annotations 204 Creating the Edit Annotation Dialog Box 206 Showing the Current Annotation 208 Retrieving the Edited Annotation 210 Conclusion 214
Chapter 8
Chapter 9
The Atomic Caf~ Introduction 215 File Previews: The Sequel 216 Removing Existing Previews 217 Finding and Counting Atoms 219 Finding the Preview Data Atom 223 Removing and Freeing Atoms 224 Shortcut Movie Files 226 Atom Containers 229 Creating Atom Containers 231 Finding Atoms in Atom Containers 233 Getting Atom Data 233 Internet Connection Speed 234 Movie Tracks 237 Adding a Movie Track to a Movie 238 Creating a Movie Track Media Sample 240 The Code 243 Conclusion 244
215
Somewhere I'll Find You
245
Introduction
245
Data Handler Overview
viii
Contents
246
The File Data Handler 248 Opening a Movie File 249 Creating a Reference Movie File 250 The Handle Data Handler 254 The Resource Data Handler 257 The URL Data Handler 258 The Pointer Data Handler 261 File Transfer 262 Creating the Local File 263 Opening and Configuring Data Handlers Transferring Data Synchronously 264 Transferring Data Asynchronously 265 Tasking the Data Handlers 268 Finishing Up 269 Data Reference Extensions 273 Conclusion 276
Chapter 10
264
Word Is Out Introduction 277 The Edit Menu Revisited 281 Emulating QuickTime Player 283 Getting the Modifier Keys on Windows 285 Renaming the Edit Menu Items on Windows Putting It All Together 289 Text Importing 291 Importing Text from the Clipboard 291 Importing Text from a File 292 Text Tracks 294 Adding Text Media Samples 294 Positioning a Text Track 297 Enabling or Disabling a Text Track 298 Creating a Text Track 298 Text Searching 302 Text Editing 306 Getting the Current Text 307 Finding Sample Boundaries 308 Chapter Tracks 310 Hypertext Reference Tracks 314 Some Loose Ends 315 Conclusion 318
277
287
Contents
ix
Chapter 11
319
Timecode
Introduction 319 Timecode Standards 321 Timecode in QuickTime 323 Timecode Tracks 324 Creating a Timecode Sample Description 325 Creating a Timecode Media Sample 328 Setting the Timecode Track Geometry 330 Creating a Track Reference 332 Timecode Track Operations 336 Getting Information about a Timecode Track 337 Showing and Hiding a Timecode Track 338 Deleting a Timecode Track 340 Conclusion 342
Chapter 12
Chapter 13
x
Contents
2001: A Space Odyssey Introduction 343 Endian Issues 344 Working with Movie User Data 345 Reading and Writing Resource Data 347 The QuickTime Media Layer 350 Avoiding Namespace Collisions 351 Working with Files 352 Working with Resources 354 Working with Modal Dialog Boxes 355 Working with Modeless Dialog Boxes 361 Handling Strings 363 Converting Data Types 366 Handling Text 367 Carbon 367 Accessing Fields of Data Structures 368 Replacing Unsupported Functions 369 Working with Universal Procedure Pointers Conclusion 372 Honey, I Shrunk the Kids Introduction 373 Compression 375 Compressing Images 377 Getting the Image Pixel Map
343
371
373
377
Setting the Test Image 378 Installing Extended Procedures 379 Compressing the Image 383 Restricting Compressor Types 386 Compressing Image Sequences 386 Getting the Image Sequence 387 Configuring the Standard Image Compression Dialog Component Setting the Test Image 390 Displaying the Compression Settings Dialog Box 391 Adjusting the Sample Count 392 Creating the Target Movie 392 Compressing the Image Sequence 394 Finishing Up 396 Asynchronous Compression 397 Setting Up for Asynchronous Compression 398 Performing Asynchronous Compression 399 Weighing the Benefits 401 Conclusion 401 Chapter 14
Chapter 15
A Goofy Movie Introduction 403 Sprite Properties 406 Sprite Tracks 407 The Format of Key Frame Samples 40"7 The Format of Override Samples 409 Creating Sprite Tracks 409 Creating Sprite Tracks and Media 410 Setting Sprite Properties 413 Setting Sprite Images 419 Adding the Key Frame Sample to the Sprite Media Creating Override Samples 423 Setting Sprite Track Properties 424 Putting It All Together 426 Hit Testing 430 Conclusion 434
An Extremely Goofy Movie Introduction 435 Video Override Tracks 436 Building a Sprite Track 437 Adding a Video Track 439
389
403
421
435
Contents
xi
Adding a Track Reference 441 Setting the Input Map 442 Tweening 447 Graphics Mode Tweening 449 Adding a ]~veen Track 450 Setting the Input Map 453 Matrix 1k~reening 455 Building the ~veen Data Atom 455 Setting the Yween Offset and Duration Spin Tweening 457 Multimatrix Tweens 459 Conclusion 462 Chapter 16
xii
Contents
456
Wired Introduction 463 Events, Parameters, Actions 466 Specifying Events 466 Specifying Actions 468 Specifying Parameters 470 Controlling Movies Using Wired Sprites 470 Building the Sprite Track 470 Wiring Actions to Sprites 473 Setting the Track Properties 475 Setting the Track Layer 477 Setting the Movie Controller 478 Setting the Track Matrix 479 Putting It All Together 481 Wired Sprite Utilities 482 Adding Event and Action Atoms 483 Setting a Sprite Image Index 486 Variables and Conditionals 487 Setting Variables 487 Controlling Action Processing 488 Using Expressions and Operands 490 Draggable Sprites 491 Creating a Condition 492 Specifying the Conditional Expression 493 Specifying the Conditional Actions 494 Putting It All Together Again 495
463
Sprite Button Behaviors Conclusion 501
Chapter 17
Chapter 18
498
Moving Target Introduction 503 Targets 504 Targeting a Sprite 504 Targeting a Track 506 Movie-to-Movie Communication 511 Adding External Movie Targets 511 Specifying Movie Target Names and IDs 512 Retrieving Movie Target Names and IDs 516 Finding Movie Targets 518 Controlling External Movies 522 Retrieving a Movie's Own Target Name and ID Operand Targets 526 Movie-in-Movie Communication 530 Specifying Movie-in-Movie Targets 530 Using Movie-Loaded Events 531 Conclusion 532
503
523
Back In Action Introduction 533 Text Actions 535 Adding Actions to a Text Sample 536 Creating Text Actions 539 Creating Hypertext Actions 547 Key Events 549 Bouncing Sprites 552 Moving the Sprite 553 Detecting Track Rectangle Collisions 556 Colliding Sprites 560 Conclusion 563
533
Glossary
565
Index
587
About the CD
619
Contents
xiii
This Page Intentionally Left Blank
Preface
QuickTime is Apple's powerful and elegant software architecture for creating and playing back multimedia content on Macintosh and Windows computers. QuickTime is also my muse. Her p o w e r and her elegance inspired me several years ago to undertake to develop a useful tutorial on how to harness that power. I w a n t e d to chart an informative and reasonably comprehensive path through the QuickTime application p r o g r a m m i n g interfaces, investigating the v a r i o u s types of m e d i a s u p p o r t e d by Q u i c k T i m e and explaining how to integrate QuickTime movie playback into an application. This book is the fruit of those efforts. Or rather, this book is one of the fruits of those efforts, for the single book I planned to write has now grown into several books. This first book, QuickTime Toolkit, Volume One: Basic Movie Playback and Media Types, begins our journey into QuickTime programming. It shows how to use QuickTime functions to open and display a movie in a window on the screen. It also shows how to perform basic editing operations on a movie and how to save an edited movie into a file. [And that's just the first chapter!) This book shows how to work with a variety of media types, including video, still images, text, timecode, and sprites. It introduces concepts that are fundamental to QuickTime programming: movies, tracks, media, time scales, track references, atoms, atom containers, data references, media samples, sample descriptions, and a host of others. This first book ends with an in-depth look at one of the cornerstones of QuickTime interactivity: wired actions and wired sprites. The second book in this series, Q uickTime Toolkit, Volume Two: Advanced Movie Playback and Media Types, continues this journey by looking at a handful of the more advanced media types supported by QuickTime: video effects, skins, Flash, and QuickTime VR. It shows how to capture movies from sound and video input sources, broadcast movies to the Internet or a LAN, play movies full screen, and load movies asynchronously. That book ends with an important second look at data references and a first look at media sample references. Together, these two books present a detailed narrative that covers a substantial amount of what's involved in QuickTime application programming on both Macintosh and Windows computers.
Preface
xv
Development Platforms Did I mention that we'll be working with QuickTime on both Macintosh and W i n d o w s c o m p u t e r s ? From the first page to the last, I take cross-platform coding issues very seriously. Q u i c k T i m e w a s originally d e v e l o p e d on the Mac, but it has been r u n n i n g quite splendidly on W i n d o w s operating syst e m s from Q u i c k T i m e v e r s i o n 3.0 o n w a r d - - t h a t is, for well over half its existence. Virtually everything we can do w i t h QuickTime on the Mac we can also do on Windows, with very little additional programming effort. This c o m m i t m e n t to multiple platforms affects this book in some fundamental ways. The most significant influence concerns our choice of programming language and development tools. It would no doubt have been nice to rely on the services of a robust rapid application development e n v i r o n m e n t like Cocoa or PowerPlant or REALbasic or Visual Basic or Revolution. These tools abstract away most of the low-level details of constructing an application's user interface and handling user actions; this would allow us to focus more closely on the QuickTime-specific code that we need to write. But none of these RAD tools is sufficiently cross-platform or currently exposes enough of the QuickTime APIs to serve our needs. Accordingly, we'll use good old C as our primary programming language, and we'll use the standard platformspecific APIs to manage the windows, menus, dialog boxes, events, and messages of the applications we build. For instance, on Macintosh computers, we'll call NewCWindow to create a w i n d o w that contains a movie, while on Windows computers we'll call CreateWindowEx. To get the ball rolling, I've developed an application called QTShell that will form the basis of most of our work in this book and the next. We'll spend the first few chapters investigating how QTShell is put together and how we can use it to hold QuickTime code that executes on both target platforms. At first glance, the Macintosh version of QTShell may seem a bit quaint since it begins life using pre-Carbon functions like StandardGetFilePreview and StandardPutFile. (And some of the screenshots will have that oh-so-retro Mac OS 9 appearance!) This decision was deliberate and taken for a n u m b e r of reasons. The main reason is simply that Carbon-style interfaces like NavGetFi l e and NavPutFi l e have not yet migrated to Windows. I felt it would be best to begin our journey into QuickTime p r o g r a m m i n g with the simplest possible code that compiles and executes on both W i n d o w s and Macintosh computers. Not to worry, however: QTShell will gradually evolve during this journey, and by the middle of this first book it will be fully Carbonized and ready to run natively on Mac OS X. By the end of the second book, QTShell will use all the latest and greatest QuickTime and Carbon APIs.
xvi
Preface
How to Read This Book This book was written especially for software developers with little or no experience working with the QuickTime application p r o g r a m m i n g interfaces. It assumes that you know how to program on Windows or Macintosh computers, and it assumes that you are familiar with QuickTime as a multimedia technology. I firmly believe that if you read this book and its sequel in order, from beginning to end, you will acquire the knowledge and skills necessary to develop professional-grade applications that can create, display, and modify QuickTime content. At the same time, I am also convinced that these books are a significant resource for programmers who are already experienced in developing with QuickTime. I know this because I find myself continually referring to the sample applications described in these books, refreshing my memory on the particular techniques they employ for handling QuickTime movies or working with specific media types. The especial attention I give to novice QuickTime developers is manifested more in the order of explanation--the progressive disclosure of concepts--than in any limited depth of discussion. There should be plenty of useful information in these pages, sprinkled with the occasional insider tips and bits of otherwise undocumented technical details, to keep even the more experienced QuickTime programmers happy. One final point: I am of the opinion that QuickTime APIs are best studied in their natural habitat, namely, as part of functions that are designed to provide real-world application solutions. Each chapter dissects portions of one or more existing applications (whose complete source code is contained on the accompanying CDI. You should expect to encounter lots of useful code snippets along the way.
Preface xvii
Acknowledgements These books grew out of a series of articles published over the last four years in MacTech magazine. I am indebted to the staff at MacTech for giving a sustained voice to Q u i c k T i m e in their publication; t h a n k s are due to Nick DeMello, Eric Gundrum, Dave Mark, and especially to Jessica Stubblefield and Neil Ticktin. My colleagues at Apple, particularly in the QuickTime engineering group, have contributed in countless ways to my understanding of QuickTime and her foibles. A number of them have also directly influenced this book, either by reviewing portions of it or by providing sample code or sample content. I wish I could name them individually. I also wish I could thank by name those tireless colleagues in Apple's developer relations and technical publications groups with w h o m I have worked over the years. You guys rock! It is a pleasure to thank the team at Morgan Kaufmann who worked so hard to bring these books to print in amazingly short order. Special thanks are due to Elisabeth Beller, Richard Camp, and Tim Cox. I'd also like to thank Yonie Overton, Jennifer McClain, and Nancy Logan for their contributions. Finally, and not least, I should recognize Nathan and Raisa for their patience and support throughout the time I was writing these articles and books.
xviii Acknowledgements
It All Starts Today
introduction In this chapter, we'll learn how to open and display QuickTime movies and how to manage the user's interactions with those movies. This is a relatively simple task, and it's one that involves adding a fairly small a m o u n t of code to a basic working application. Keep in mind, however, that we want to support both the Mac OS and the major flavors of the Windows operating system (to wit: Windows 98, Windows NT, Windows ME, Windows 2000, and Windows XP). So we'll spend some time seeing how to open and play back movies using code that can run on both major platforms. Writing QuickTime code that is compatible with multiple platforms really isn't so hard. Indeed, part of the reason that QuickTime runs so well on Windows is that a good n u m b e r of the Macintosh programming concepts (including handles, resources, and file system specifications) were implemented on Windows as part of the QuickTime Media Layer (QTML). The hardest part of getting our QuickTime code to run on Windows may simply be creating a basic application shell or framework to hold that code. Accordingly, we'll spend a good bit of time in this chapter discussing just that issue.
M o v i e Controllers Before we start looking at our source code, however, let's take a minute to make clear what it is that we want to achieve. For the moment, we'll be content to build an application that can open and display QuickTime movies in windows on the screen. The Windows version of our basic application will have a frame window that contains a m e n u bar and within which we can open and display one or more movie windows. Figure 1.1 shows the appearance of the application's frame w i n d o w before the user has opened any QuickTime movies.
Figure 1.1
The frame window of the Windows application.
A movie w i n d o w will contain all the standard w i n d o w parts, the movie itself, and a special set of controls called the movie controller bar. Figure 1.2 shows a typical Macintosh movie window, and Figure 1.3 shows a Windows version of the same movie window. Both of these windows show the standard movie controller bar along the bottom edge of the window. The movie controller bar allows the user to control the playback of the movie and to navigate within it. For instance, the user can hold down the Frame Forward button to step the movie forward one frame at a time. Or, the user can drag the position t h u m b to set the current location in the movie. Some kinds of QuickTime movies use a different movie controller bar. For instance, QuickTime VR movies are not typically played frame by frame in a linear fashion. For these movies, you'll see the movie controller bar shown in Figure 1.4, which contains controls that allow the user to zoom in and out and to perform other operations on the movie. The movie controller bar is created and managed by a software component called a movie controller component (or, more briefly, a movie controller). Now here's the really fun part: once you've opened a QuickTime movie (using a few simple QuickTime functions), you can call a couple more functions to create and attach a movie controller to your movie. Thereafter, the
2
Chapter 1 It All Starts Today
Figure 1.2 A movie window on the Macintosh.
Figure 1.3 A movie window on Windows.
Movie Controllers
3
Figure 1,4 The movie controller bar for a QuickTime VR movie.
movie controller (and not your application} draws the movie controller bar and manages all events associated with the movie. Your application doesn't need to know how to jump to a new location in the movie or how to start and stop the movie playback. It simply needs to pass any events it receives to the movie controller component before acting on them itself. The movie controller intercepts any events that apply to it and reacts to them appropriately. So, the first lesson we need to take to heart is this: we can get all the basic movie playback capabilities simply by creating a movie controller, attaching it to our movie, and then giving it the first shot at handling any events we receive. And as if that weren't enough, the movie controller also provides an extremely easy way for us to perform basic editing operations on movies that support them. (Not all movies support cutting, copying, or pasting of movie segments; for instance, QuickTime VR movies do not.}
The Application Framework Now it's time for a bit of a detour. QuickTime provides an extensive set of services for handling digital media like sound, video, sprite animation, and the like. But of course we'll need to use other services to handle the basic graphical user interface for our QuickTime-savvy application--that is, its windows, menus, dialog boxes, and so forth. If you're an experienced Macintosh programmer, you're already familiar with the ideas underlying eventdriven programming on the Macintosh. Windows uses a slightly different
4
Chapter 1 It All Starts Today
idiom, sending messages to specific windows in an application. Since we want to support QuickTime programming on both Macintosh and Windows systems, we'll need to address separately the issues specific to each operating system, while trying to factor out as much code as possible to share between the two systems. Our general approach will go like this: we'll create two files, MacFramework. c and WinFramework. c, that handle the basic application services that are specific to the Macintosh and Windows operating systems, respectively. These services include starting up and shutting down the application, handling events and messages, creating windows, opening files dropped onto the application icon, and so forth. We won't delve very much into these framework files in this chapter, since there isn't very much in them of interest to QuickTime programmers. Suffice it to say that the Macintosh framework would look very familiar to anyone who cut his or her Mac programming eyeteeth in the late 1980s or 1990s; it uses standard event-driven programming techniques to handle the user's actions. And the Windows framework is a very straightforward implementation of the multiple document interface [MDI) specification defined by Microsoft for creating and managing one or more document windows within a general frame window. What's nice about MacFramework.c and WinFramework.c is that they have been carefully designed to call functions defined in a third file, ComFramework.c, for most QuickTime services or other services that are not systemspecific. ComFramework.c also defines a number of functions that are substantially the same on both platforms but that may require several short platform-dependent blocks (introduced by the compiler flags TARGET OS MAC and TARGET OS_WIN32). Keep in mind that (in this chapter, at least) we want to support only the most basic playback and editing of QuickTime movies, which is exactly what is provided by the basic framework. In future chapters, however, we'll want to add other capabilities to our applications. For instance, we'll want to handle some new menus in addition to the standard File and Edit menus, and we'll want to perform some application-specific tasks at idle time (perhaps change the pan angle of a QuickTime VR movie). To make it easy to add such capabilities, we create yet another file, called ComApplication.c, which defines a number of functions that are called at particular times by the basic framework. For instance, after the framework does any necessary menu adjusting for the File and Edit menus (enabling certain menu items and disabling others), it calls the function QTApp_AdjustMenus, defined in ComAppl i cation.c, to allow us to adjust any application-specific menus. Since we don't have any application-specific tasks to perform, for the moment at least, we can ignore ComApplication.c and instead turn our attention to the file ComFramework.c.
The Application Framework
5
Handling Movie Windows To get a taste for how our basic f r a m e w o r k works, let's begin by considering how we w a n t to m a n a g e o u r application's movie windows. On the Macintosh, a movie w i n d o w is of type WindowPtr; on Windows, a movie w i n d o w is of type HWND.To simplify the code that handles movie windows, we define a custom type that refers to either a Macintosh movie w i n d o w or a W i n d o w s movie window, like this" #if TARGETOS MAC typedef WindowPtr #endif #if TARGETOS WIN32 typedef HWND #endif m
WindowReference;
m
WindowReference;
We need to maintain some information for each movie w i n d o w displayed by our application. We'll use the standard technique of defining a structure to hold this information and allocating an instance of that structure for each open movie window. Let's call this instance a window object record. typedef struct { WindowReference fWi ndow; Movie fMovie; MovieControl ler fControl ler; FSSpec fFi I eFSSpec; short fFileResID; short fFi I eRefNum; Boolean fCanResi zeWindow; Boolean flsDirty; Boolean f l sQTVRMovie; QTVRInstance flnstance; OSType fObj ectType; Handle fAppData; } WindowObjectRecord, *WindowObjectPtr, **WindowObject;
Notice that the first field of this structure, fWindow, is of type WindowReference, which (as we've just seen) is a WindowPtr on the Mac and an HWNDon Windows. The fMovie and fControl l er fields identify the movie and movie controller. The next three fields maintain information about the location of the movie file on disk and in memory. The three fields after that indicate w h e t h e r the movie w i n d o w can be resized (which is almost always true), w h e t h e r the movie data has changed since it was opened or last saved, and
6
Chapter 1 It All Starts Today
w h e t h e r the movie is a QuickTime VR movie. If the movie is a Q u i c k T i m e VR movie, the fInstance field holds a special identifier associated with the movie. The f0bjectType field holds an arbitrary identifier that is u n i q u e to our application; we use this field just to make sure that w e ' v e got a valid w i n d o w object. Finally, the fAppData field holds a handle to any applicationspecific data. For now, we w o n ' t need to use this field. W h e n the user selects a movie file to open, we need to allocate a w i n d o w object record and attach it to the w i n d o w in w h i c h the movie is opened. The standard Macintosh w a y to do this is to use the SetWRefCon function to set the w i n d o w ' s reference constant, an application-specific 32-bit value, to the handle to the w i n d o w object record. W i n d o w s provides a similar capability to attach an application-specific 32-bit value to a window, w i t h the SetWindowLong function. Listing 1.1 shows the code we use for creating a window object.
Listing 1.1 Creating a window object. void QTFrame CreateWindowObject (WindowReference theWindow)
{
WindowObject
myWindowObject= NULL;
i f (theWindow == NULL) return; / / allocate space for a window object record and f i l l in some of i t s fields myWindowObject = (Wi ndowObject) NewHandI eCl ear (s i zeof (Wi ndowObject Record) ) ; i f (myWindowObject ! = NULL) { (**myWindowObject).fWindow = theWindow; (**myWindowObject) .fControl ler = NULL; (**myWindowObject) .fObjectType = kMovieControl lerObject; (**myWindowObject).flnstance = NULL; (**myWindowObject).fCanResizeWindow = true; (**myWi ndowObject), f l sDi rty = false; (**myWi ndowObject), fAppData = NULL;
/ / associate myWindowObject (which may be NULL) with the window # i f TARGET OS MAC SetWRefCon(theWindow, (long)myWindowObject) ; #endif # i f TARGET OS WIN32 SetWindowLong(theWindow, GWL USERDATA, (LPARAM)myWindowObject); B
/ / associate a GrafPort with this window CreatePortAssociation(theWindow, NULL, OL); #endif
The Application Framework
7
/ / set the current port to the new window MacSetPort (QTFrame GetPortFromWindowReference(theWi ndow)) ;
Internally, QuickTime does some of its drawing using QuickDraw, the collection of system software routines that perform graphic operations on the user's screen (and elsewhere). And, as you know, QuickDraw does all of its drawing within the current graphics port. On the Macintosh, there is a very close connection between a WindowPtr and a graphics port, but there is no such connection between Windows HWNDsand graphics ports. So, w h e n our application is running on Windows, we need to call the CreatePortAssociation function to create a connection between the HWNDand a graphics port (of type GrafPtr). Once we've called CreatePortAssociation to associate a graphics port with an HWND,we can subsequently call the GetNativeWindowPort function to get a
pointer to the graphics port that is associated with that window. Listing 1.2 defines a function that we can call from either Macintosh or Windows code to get a window's graphics port. (Now you can understand the last line in Listing 1.1, which sets the current graphics port to the port associated with the specified window.l Listing 1.2: Getting the graphics port associated with a window. GrafPtr QTFrame GetPortFromWindowReference (WindowReference theWindow)
{
m
#if TARGETOS MAC return((GrafPtr) GetWindowPort(theWi ndow)); #endif #if TARGETOS WIN32 return (GetNati veWindowPort(theWi ndow)) ; #endif m
}
Let's look briefly at a few other small utilities that we'll use extensively in our framework code. Keep in mind that our general goal here is to provide utilities that insulate us from the specific details of any particular operating system. One thing we'll need to do fairly often is retrieve the windowspecific data that we've stored in the window object record associated with a given movie window. We can use the OTFrame_GetWindowObjectFromWindow function, defined in Listing 1.3, to do this. Aside from a few sanity checks (namely, the calls to QTFrame_IsAppWindow and QTFrame_IsWindowObjectOurs), this function is essentially the reverse of attaching the window object record to a window.
8
Chapter 1 It All Starts Today
Listing 1.3 Getting the window-specific data. WindowObject QTFrame_GetWindowObjectFromWi ndow (Wi ndowReference theWindow)
{
WindowObject
myWindowObject= NULL;
i f (!QTFrame_IsAppWindow(theWindow)) return(NULL) ; #if TARGETOS MAC myWindowObject = (Wi ndowObject) GetWRefCon(theWi ndow) ; #endif #if TARGETOS WIN32 myWindowObject = (WindowObject)GetWindowLong(theWindow, GWL USERDATA); #endif / / make sure this is a window object i f ( ! QTFrame_IsWi ndowObjectOurs (myWindowObject) ) return (NULL) ; return (myWindowObject) ;
Finally, we'll often need to iterate through all open movie windows. On Windows, this is fairly simple since the operating system provides an easy way for us to ask for the first (or next) child of the MDI frame window, which we know to be a movie window. On the Macintosh, it's a bit harder since we need to skip over any dialog windows or other types of w i n d o w s that might be in our w i n d o w list. We can use the functions QTFrame GetFrontAppWindow and QTFrame_GetNextAppWindow, defined in Listings 1.4 and 1.5, to step through all open windows that belong to our application.
Listing 1.4 Getting the first application window. WindowReference QTFrame_GetFrontAppWindow (void)
{
#if TARGETOS MAC return (FrontWi ndow() ) ; #endif #if TARGETOS WIN32 return(GetWindow(ghWnd, GWHWNDFIRST)); #endif m
}
The Application Framework
9
One thing to notice in Listing 1.5 is that we did not find the next w i n d o w by reading the nextWi ndow field of the w i n d o w record, as used to be standard practice. Instead, we've used the accessor function GetNextWindow defined in the header file MacWindows.h. Here we're treating the w i n d o w record as an opaque data structure and thereby facilitating our eventual move to Carboncompatible APIs. [For more on Carbon, see page 113.)
Listing 1.5 Getting the next application window. WindowReference QTFrame GetNextAppWindow (Wi ndowReference theWindow)
{
# i f TARGET OS MAC return(theWindow == NULL ? NULL : GetNextWindow(theWindow)); #endi f # i f TARGET OS WIN32 return(GetWindow(theWindow, GW HWNDNEXT)); #endi f
}
To find the front movie w i n d o w on the Macintosh, we'll just walk through the w i n d o w list until we find the first w i n d o w with a non-NULL w i n d o w object attached to it, as shown in Listing 1.6.
Listing 1.6 Getting the first movie window. WindowReference QTFrame GetFrontMovieWindow (void)
{
WindowReference
myWindow;
# i f TARGET OS MAC myWindow = QTFrame_GetFrontAppWindow() ; while ((myWindow ! = NULL) && (QTFrame_GetWindowObjectFromWindow(myWindow) == NULL)) myWindow = QTFrame_GetNextAppWindow(myWindow) ; #endi f # i f TARGET OS WIN32 myWindow = (HWND)SendMessage(ghWndMDIClient, WMMDIGETACTIVE, O, OL); #endif m
return (myWindow) ;
10
Chapter 1 It All Starts Today
And to get the movie w i n d o w that follows a specific movie window, w e ' l l continue walking t h r o u g h the w i n d o w list until w e find the next w i n d o w w i t h a non-NULL w i n d o w object, as s h o w n in Listing 1.7.
Listing 1.7 Getting the next movie window. WindowReference QTFrame_GetNextMovieWi ndow (Wi ndowReference theWi ndow)
{
WindowReference
myWindow;
# i f TARGET OS MAC myWindow = QTFrame_GetNextAppWindow(theWi ndow) ; while ((myWindow ! = NULL) && (QTFrame_GetWindowObjectFromWindow(myWindow) == NULL)) myWindow = QTFrame GetNextAppWindow(myWindow) ; #endif m
# i f TARGET OS WIN32 myWindow = GetWindow(theWindow, GW HWNDNEXT); #endif return (myWindow) ;
Handling Menus Now we w a n t to do the s a m e thing for m e n u s that w e ' v e done for w i n d o w s , namely, develop a unified w a y to refer to m e n u s and m e n u items, so that we can (for instance) enable and disable m e n u items or process the user's selection of m e n u items in a platform-neutral m a n n e r . Happily, this is a simpler task than the one we just solved. On the Macintosh, a particular m e n u item is specified using two pieces of information, the m e n u ID and the index of the i t e m in the specified m e n u . On Windows, a m e n u item is specified by a single, 16obit " m e n u item identifier," w h i c h is an arbitrary value that we associate w i t h the m e n u item. Because the value on W i n d o w s is arbitrary, we'll construct it by setting the high-order 8 bits to the Macintosh m e n u ID and the low-order 8 bits to the index of the m e n u item in the m e n u . Suppose we use the following values for the m e n u bar and m e n u resource IDs in our Macintosh resource file: #define #define #define #define
kMenuBarResID kAppleMenuResID kFi leMenuResID kEditMenuResID
128 128 129 130
The Application Framework
11
Then we can define our m e n u item identifiers like this: #define #define #define #define #define #define #define
IDS IDM IDM IDM IDM IDM IDM
FILEMENU FILENEW FILEOPEN FILECLOSE FILESAVE FILESAVEAS EXIT
33024 33025 33026 33027 33028 33029 33031
/ / (kFi leMenuResID<<8)+O / / (kFi I eMenuResID<<8)+1
#define #define #define #define #define #define #define
IDS EDITMENU IDM EDITUNDO IDM EDITCUT IDM EDITCOPY IDM EDITPASTE IDM EDITCLEAR IDM EDITSELECTALL
33280 33281 33283 33284 33285 33286 33288
/ / (kEdi tMenuResI D<<8)+0 / / (kEdi tMenuResID<<8)+1
You might be wondering w h y we didn't just define, for instance, IBS_FILEMENU as (kFileMenuResID<<8)+0. In fact, this works fine w h e n developing either Mac or Windows applications using CodeWarrior, but it doesn't seem to work w h e n using Microsoft Developer Studio on Windows machines. Go figure--literally! Also, for those of you with calculators that don't have a "<<" key, bit-shifting left by 8 is the same as multiplying by 256. In effect, w e ' r e simply adopting the Windows method of specifying m e n u items, but doing so in a m a n n e r that allows us to retrieve the Macintosh m e n u ID and m e n u item index from the arbitrary m e n u item identifier, using these macros: #define MENUIDENTIFIER(menuID,menultem) #define MENU ID(menuldentifier) #define MENU ITEM(menuIdentifier) m
( (menuI D<<8)+(menuItem) ) ( (menuIdenti fi er&OxffO0)>>8) ( (menuIdenti fi er&OxOOff) )
Now we need to devise a way of referring to m e n u s themselves in a crossplatform way. On the Macintosh, we access m e n u s using variables and parameters of type MenuHandle, while on Windows, we use variables and parameters of type HMENU.Once again, we'll define a custom type that refers to either a Macintosh m e n u or a Windows menu, like this: #if TARGETOS MAC typedef MenuHandle #endif #if TARGET OS WIN32 typedef HMENU #endif
12
Chapter 1 It All Starts Today
MenuReference;
MenuReference;
Let's see how this all fits together in practice. Suppose we w a n t to enable or disable a particular m e n u item. For instance, the user m a y have edited a movie window, in which case we want to make sure that the Undo m e n u item in the Edit m e n u is enabled. We can use the function QTFrame SetMenuItemState defined in Listing 1.8. m
Listing 1.8 Enabling or disabling a menu item. void QTFrame_SetMenultemState (MenuReference theMenu, UInt16 theMenultem, short theState)
{
#if TARGET OS MAC i f (theState == kEnableMenuItem) EnableMenultem(theMenu, MENU ITEM(theMenultem)) ; else Di sabl eMenuI tem(theMenu, MENU_ITEM(theMenuItem) ) ; #endif #if TARGET OS WIN32 EnableMenultem(theMenu, (UINT)theMenultem, (UINT)theState); #endif n
}
On Windows, QTFrame_SetMenultemState uses the Windows function EnableMenuItem to set the specified m e n u item to the desired state. On the Macintosh, it calls either of the two Macintosh functions EnableMenuItem or Di sabl eMenuItem, depending on the value of theState.
QuickTime Support Now let's get back to the task at hand, w h i c h is showing how to open and display QuickTime movies and how to handle basic editing operations on those movies.
Opening a Movie File Let's suppose that w e ' v e already got a file s y s t e m specification record that indicates which movie file the user wants to open. We might have called the Standard File Package or (on Macintosh) the n e w e r Navigation Services to elicit a file from the user, or we might have gotten the file specification from an O p e n D o c u m e n t Apple event. At this point, we can call the f u n c t i o n OpenMovieFi le to open the movie file: myErr = OpenMovieFile(&myFSSpec, &myRefNum, fsRdWrPerm) ;
QuickTime Support
13
Next we need to load the movie data from the file. We can do this by calling the NewMovieFromFi l e function, as follows" myResID = O; myErr = NewMovieFromFile(&myMovie, myRefNum, &myResID, NULL, newMovieActive, NULL);
N o w we need to create a w i n d o w in w h i c h to display the movie. This operation is platform-specific" on the Macintosh, we can call the NewCWindow function, and on Windows, we can call the CreateWindowEx function. Once w e ' v e successfully created a window, we just need to pass that w i n d o w to the OTFrame_CreateWindowObject function defined in Listing 1.1, w h i c h (as we saw) allocates some m e m o r y to hold information n e e d e d by our f r a m e w o r k s and attaches the w i n d o w object record to the window.
A t t a c h i n g a M o v i e Controller So, at this point, w e ' v e o p e n e d the movie file and read the movie data from it. We've also created a w i n d o w {which is not yet visible), created a w i n d o w object, and attached the w i n d o w object to the window. Before we can m a k e the movie w i n d o w visible, we need to create a movie controller and attach it to the window. We do this by calling the f r a m e w o r k function OTFrame_SetupController" myMC = QTFrame_SetupController(myMovie, myWindow, true) ;
The QTFrame_SetupControl l er function is a tad lengthy, so we w o n ' t show it all here. But it does only four things of any real interest: it creates a new movie controller for the specified movie; it enables movie controller editing; it adds a grow box to the movie controller bar; and it installs a movie controller action filter function. We'll discuss movie editing a little later; for now, let's see how to do the other three tasks. Before we can create a movie controller, we need to d e t e r m i n e the rectangle within w h i c h the movie is going to be displayed. O u r basic application draws the movie at its natural size, w h i c h we can obtain by calling the GetMovieBox function (making sure that the top-left corner of the movie is at
0,0)" GetMovieBox(myMovie, &myRect); MacOffsetRect (&myRect, -myRect. 1eft, -myRect.top) ; SetMovi eBox(myMovie, &myRect);
14
Chapter 1 It All Starts Today
Then we can create a movie controller with this single line of code: myMC = NewMovieController(myMovie, &myRect, mcTopLeftMovie) ;
Even though we've opened the movie at its natural size, w e ' d like to allow the user to resize the movie window. By default, the movie controller does not provide this capability, so we need to do a little w o r k to enable movie resizing. The first thing we need to do is find the upper bounds for the movie w i n d o w size. In other words, we need to find the largest rectangle that can contain a movie window. We could set an arbitrary upper b o u n d for our movie w i n d o w size, but instead we'll allow the user to resize a movie to fit as m u c h of the available screen space as possible. On the Macintosh, we can get this area like this" gMCResi zeBounds = (**GetGrayRgn ()). rgnBBox;
(This line of code isn't Carbon-compliant, of course. We still have a little bit of w o r k to do before our M a c i n t o s h f r a m e w o r k is fully Carbonized.) O n Windows, we can call the GetOesktopWindow and GetWindowRect functions to get the size of the desktop. Note that GetWi ndowRect r e t u r n s a s t r u c t u r e of type RECT, w h i c h on W i n d o w s consists of four long integers. So we need to convert the RECTinto a Rect, like this: RECT
myRect;
GetWindowRect(GetDesktopWindow(), &myRect) ; OffsetRect (&myRect, -myRect. I eft, -myRect. top) ; gMCResizeBounds, top = (short)myRect. top; gMCResizeBounds.left = (short)myRect.left; gMCResi zeBounds, right = (short)myRect. r i g h t ; gMCResizeBounds, bottom = (short)myRect. bottom;
Then, we can enable w i n d o w resizing by calling the MCDoAction function with the mcActi onSetGrowBoxBounds parameter: MCDoActi on (myMC, mcActi onSetGrowBoxBounds, &gMCResi zeBounds) ; MCDoAction is a general-purpose tool for getting a movie controller to perform various actions. (If we take a look in Movies.h, a standard header file provided by QuickTime, we'll see well over 60 defined movie controller actions.) We'll use MCDoAction extensively throughout this book. For the moment, though, it's important to know that before the movie controller performs any action initiated by MCDoAction, it informs our application of the
QuickTime Support
15
pending action and, indeed, allows it to cancel that action. To get these notifications of pending actions, we need to install a movie controller action filter function, like this" MCSetActi onFi I terWi thRefCon (myMC, NewMCActi onFi I terWi t hRefConProc (QTApp_MCActi onFi I terProc), (l ong)myWindowObject) ;
The first p a r a m e t e r is the movie controller to w h i c h we want to attach a filter function. The second p a r a m e t e r is a universal procedure pointer f o r the filter function itself. The third p a r a m e t e r is an application-specific reference constant that is passed to the filter function w h e n e v e r it is called. As you can see, w e ' r e passing the w i n d o w object to the filter function so that we can gain access to the movie w i n d o w ' s data inside that function. Listing 1.9 shows a typical movie controller action filter function. This function handles only one action, mcActionControl lerSizeChanged, which the movie controller sends to our filter function w h e n e v e r the user has dragged the resize box in the controller bar. Our job is then to resize the associated movie window.
Listing 1.9 Intercepting movie controller actions. PASCAL_RTN Boolean QTApp_MCActionFilterProc (MovieController theMC, short theAction, void *theParams, long theRefCon)
{
#pragma unused(theMC, theParams) Boolean
WindowObject
i sHandl ed = fal se; myWindowObject = NULL;
myWindowObject = (Wi ndowObject)theRefCon; i f (myWindowObject == NULL) return (i sHandl ed) ; swi tch (theActi on) { / / handle window resizing case mcActionControl lerSizeChanged" QTFrame_SizeWindowToMovie (myWindowObject) ; break; default" break;
} return (i sHandled) ;
16
Chapter 1 It All Starts Today
A movie controller action filter function should r e t u r n fa] se as its function result if it w a n t s the movie controller to handle the action specified by the theAction parameter. Conversely, it should r e t u r n true if it d o e s n ' t w a n t the movie controller to handle the action. In the case of the mcActionControl]erSizeChanged action, we r e t u r n fa] se to let the controller do a n y processing it needs to.
Handling Events Once w e ' v e got a movie file o p e n e d in a w i n d o w and have attached a movie controller to it, we need to let the movie controller handle any events that apply to it. (For instance, if the user hits the space bar, the movie controller should start or stop the movie, d e p e n d i n g on its current playing state.) The main thing we need to do is pass the event to the MCIsPlayerEvent function, but how we do this differs b e t w e e n the Mac and W i n d o w s platforms. On Macintosh, we get events in our main event loop by calling Wai tNextEvent. W h e n we retrieve an event in this way, we d o n ' t k n o w to which, if any, movie controller it might apply. So, we'll just pass the event to all open movie controllers until we find one that accepts it. Listing 1.10 shows h o w we do this. Listing 1.10 Handling events on the Macintosh. static Boolean QTFrame_CheckMovieControllers (EventRecord *theEvent)
{
Wi ndowPtr WindowObject Movi eControl I er
myWindow; myWindowObject; myMC;
myWindow = QTFrame GetFrontMovieWindow(); while (myWindow != NULL) { myWindowObject = QTFrame GetWindowObjectFromWi ndow(myWindow) ; i f (myWindowObject ! = NULL) { myMC = (**myWindowObject).fController; i f (myMC ! = NULL) i f (MCIsPlayerEvent(myMC, theEvent)) return(true) ; n
m
}
myWindow = QTFrame_GetNextMovieWi ndow(myWindow) ; return(false);
QuickTime Support
17
On Windows, however, system and user actions are handled s o m e w h a t differently. Windows sends messages describing those actions directly to the w i n d o w procedure of the target window, so we k n o w in advance to w h i c h movie controller the action might apply. The only "gotcha" is that MClsPlayerEvent wants to get Macintosh-style events, not Windows-style messages. So we need to call the function WinEventToMacEvent to translate the Windows message into a Macintosh event, as shown in Listing 1.11.
Listing 1.11 Handling events on Windows. WinEventToMacEvent(&myMsg, &myMacEvent); / / pass the Mac event to the movie controller i f the movie window i s n ' t minimized i f (! Islconic(theWnd)) MCIsPI ayerEvent (myMC, (EventRecord *)&myMacEvent) ;
Editing a Movie Some QuickTime movie controllers support the typical cut, copy, paste, and clear editing operations t h r o u g h a handful of high-level functions that are very easy to use. By default, a newly created movie controller has editing turned off, so we need to explicitly turn it on, like this: MCEnableEditing(myMC, true) ;
If we're interested in finding out w h e t h e r a particular movie controller supports editing, we can inspect the value returned by MCEnableEditing, which is nonzero if the specified movie controller does not support editing. We'll ignore that return value here, since we'll dynamically determine whether a movie controller supports editing w h e n e v e r we adjust our application's menus. W h e n the user chooses an item in our Edit m e n u [or performs some equivalent keyboard operation), we simply need to call the corresponding movie controller function. For instance, if the user chooses the Cut m e n u item, we'll call the MCCut function and also set a flag to indicate that the movie's data has changed: myMovie = MCCut(myMC); (**myWindowObject).flsDirty : true;
MCCut removes the current movie selection from the movie associated with the specified movie controller. Moreover, MCCut returns the cut movie selection to us; this is useful if we want to allow the user to paste that seg-
18
Chapter 1 It All Starts Today
m e n t back into the same movie (or indeed into some other movie). We need to call the PutMovieOnScrap function if we w a n t to allow that segment to be pasted. Listing 1.12 shows our entire function for handling the Edit menu.
Listing 1.12 Handling items in the Edit menu. void QTFrame_HandleEditMenultem (WindowReference theWindow, UInt16 theMenultem)
{
WindowObject MovieControl ler Movie
myWindowObject = NULL; myMC = NULL; myMovie = NULL;
myWindowObject = QTFrame_GetWindowObjectFromWi ndow(theWi ndow) ; myMC = QTFrame GetMCFromWindow(theWi ndow) ; / / make sure we have a valid movie c o n t r o l l e r and a valid window object i f ((myMC == NULL) II (myWindowObject == NULL)) return; switch (theMenultem) { case IDM EDITUNDO: MCUndo(myMC); (**myWi ndowObject), f l sDi rty = case IDM EDITCUT: myMovie = MCCut(myMC); (**myWi ndowObject), f l sDi rty = case IDM EDITCOPY: myMovie = MCCopy(myMC); case IDM EDITPASTE: MCPaste(myMC, NULL); (**myWi ndowObject), f l sDi rty = case IDM EDITCLEAR: MCCIear (myMC) ; (**myWi ndowObject), f l sDi rty = case IDM EDITSELECTALL: QTUti I s SelectAl IMovie(myMC) ; default:
true;
break;
true;
break; break;
true;
break;
true;
break; break; break;
/ / place any cut or copied movie segment onto the global scrap i f (myMovie I = NULL) { PutMovieOnScrap(myMovie, OL) ; Di sposeMovi e (myMovi e).;
}
QuickTime Support
19
The movie controller also provides an easy w a y for us to d e t e r m i n e w h i c h Edit m e n u items need to be enabled or disabled at any time. The function MCfetContro] ]erInfo returns a 32-bit set of flags that we can inspect to see the current status of the movie controller, such as w h e t h e r the user has edited the movie. So, to enable or disable the U n d o m e n u c o m m a n d , we can use code like this: MCGetControl lerlnfo(myMC, &myFlags) ; i f (myFlags & mclnfoUndoAvailable) QTFrame_SetMenuItemState (myMenu, I DM_EDI TUNDO, kEnableMenuI tem) ; else QTFrame SetMenuItemState(myMenu, IDM EDITUNDO, kDi sabl eMenultem) ; See the function QTFrame_AdjustMenus in ComFramework.c for the complete story on adjusting all the Edit (and File) m e n u items.
Conclusion Well, w e ' v e accomplished w h a t we set out to do, namely, show how to open QuickTime movie files in movie w i n d o w s and handle user interactions with those movies. Along the way, we also took a fairly long look at some of the techniques we can use, here and in the future, to make sure that our code operates identically on both Macintosh and W i n d o w s operating systems. By spending the time now to u n d e r s t a n d how to use the p l a t f o r m - i n d e p e n d e n t utilities defined in ComFramework.c, we have (I hope) m a d e it easier to spend time later focussing on the QuickTime-specific tasks we w a n t to accomplish.
20
Chapter 1 It Aft Starts Today
Control
Introduction In the previous chapter, we learned how to open QuickTime movies and display them in windows on the screen. We also learned how to create movie controllers and pass events to them so that the user can interact with the movies in the standard ways. For normal "linear" QuickTime movies, these basic interactions include starting and stopping the movie, moving quickly forward or backward in the movie, adjusting the volume of the sound track, and performing simple editing operations on the movie. For QuickTime VR movies, the basic interactions include changing the pan and tilt angles, zooming in or out, moving from one node to another, and displaying the visible hotspots. All of this interaction is provided, with virtually no programming on our part, by the movie controller associated with the movie. In this chapter, we're going to continue working with movie controllers. Now that we've done all the work necessary to associate a movie controller with a movie and to draw the movie and movie controller bar in a w i n d o w on the screen, there is a tremendous amount of "low-hanging fruit" that we can pick with a very small amount of code. Here we'll see how to hide and show the movie controller bar, hide and show particular buttons in the bar, attach a pop-up m e n u to the custom button in the controller bar, and perform several other tasks on the controller bar. Toward the end of this chapter, I'll also throw in a few goodies that are only slightly more complicated, like getting a movie controller to open a URL in the user's default Web browser. Along the way, we'll take a look at movie user data, which is some custom data that can be attached to a movie. We can use a movie's user data to specify lots of information about a movie, including the initial position of the movie window, the movie's looping state, and the movie's copyright information. This isn't completely unrelated to our main topic in this chapter, because movie controllers and movie user data are linked in one important
21
way: for a movie to use a special movie controller (that is, any controller other than the standard linear movie controller), the movie's user data must include a piece of information that specifies which other controller to use. W h e n we call NewMovieController to associate a movie controller with an open movie, QuickTime looks for that piece of user data and, if it finds it, opens the specified movie controller. Here we'll see how we too can inspect that data and use it for our own purposes.
M a n a g i n g the Controller Bar Before we begin, it's worthwhile to emphasize once again the distinction between a movie controller and a movie controller bar. A movie controller is a software component that we can use to manage the user's interaction with a QuickTime movie. A movie controller bar is a visible set of controls and other user interface elements that is displayed by a movie controller (usually along the bottom of the movie window) and that provides some ways for the user to interact with the movie. The movie controller typically supports some forms of user interaction that are not associated with the controller bar (for instance, hitting the space bar starts or stops a linear QuickTime movie). Moreover, it's possible to have a movie controller associated with a movie but no visible movie controller bar (as we'll see shortly); even w h e n the movie controller bar is hidden, the user can still interact with the movie. This distinction needs emphasizing only because it's not u n c o m m o n to hear people talk about the movie controller w h e n they really m e a n the movie controller bar.
Showing and Hiding the Controller Bar So let's get started picking some of that low-hanging fruit. One of the simplest things we can do is hide the movie controller bar, with this single line of code" MCSetVisible(myMC, false) ;
(Here myMC refers to a movie controller.} The MCSetVisi bl e function sets the controller bar to be visible or invisible, according to the Boolean value we pass it. Figure 2.1 shows a movie w i n d o w with the controller bar hidden. Let's take a m o m e n t to define a couple of functions that call MCSetVisible with the appropriate parameter, mainly to give ourselves a more uniform naming convention and to make our code a bit more readable. Listing 2.1 defines the function QTUtils_HideControllerBar and Listing 2.2 defines the opposite function, QTUti 1s_ShowControl 1erBar.
22
Chapter2 Control
Figure 2.1 A movie window with a hidden movie controller bar. Listing 2.1
Hiding the controller bar.
void QTUtils HideControllerBar (MovieController theMC)
{
}
MCSetVisible(theMC, false) ;
Listing 2.2. Showing the controller bar.
void QTUtils ShowControllerBar (MovieController theMC)
{
}
m
MCSetVisible(theMC, true) ;
We can call the MCGetVisible function to determine w h e t h e r the controller bar is currently visible, as shown in Listing 2.3. Listing 2.3 Determining whether the controller bar is visible.
Boolean QTUtils IsControllerBarVisible (MovieController theMC)
{
}
m
return( (Boolean) MCGetVisi bl e (theMC)) ;
Managing the Controller Bar
23
And we can put this all together to define a function that toggles the current visibility state of the controller bar, as shown in Listing 2.4.
Listing 2.4 Toggling the visibility state of the controller bar. void QTUtiI s_ToggleControl lerBar (MovieControl ler theMC)
{
i f (QTUtils IsControllerBarVisible(theMC)) QTUti I s Hi deControl lerBar(theMC) ; else QTUti Is ShowControllerBar(theMC) ;
No doubt there are more than a few of you out there scratching your heads and wondering w h y we didn't simply define QTUti l s_ToggleControl l erBar with this single line of code" MCSetVisible(theMC, ! (Boolean)MCGetVisible(theMC)) ; We surely could have done that, but personally I find the definition in Listing 2.4 to be a tad more readable.
Using Badges While we're on the topic of hiding and showing the controller bar, it's w o r t h mentioning a useful but little-used user interface element k n o w n as a badge. The idea behind badges is that a movie w i n d o w that has no controller bar and whose movie is not actively playing looks remarkably like a w i n d o w containing a still picture. (Take another look at Figure 2.1.} To help the user realize that the w i n d o w is actually a movie w i n d o w containing a stopped movie with no visible controller bar, the movie controller can be made to display a badge, as seen in Figure 2.2. The movie controller displays the badge w h e n e v e r the movie is stopped and there is no visible movie controller bar, but only if we have previously configured the movie controller to do so, like this: MCDoAction(myMC, mcActionSetUseBadge, (void *)true); A useful feature of a badge is that the user can make the controller bar reappear by clicking in the badge. If we want, we can explicitly disable the movie controller from using a badge by executing this line of code: MCDoAction(myMC, mcActionSetUseBadge, (void *)false);
24
Chapter 2 Control
Figure 2.2 A movie window displaying a badge.
You'll find that line in the function QTFrame SetupControl l er in our source code file ComAppl i c a t i o n . c to s u p p r e s s badge display for any m o v i e s we display.
Attaching and Detaching the Controller Bar The default behavior of a movie controller is to draw the movie controller bar contiguous to, and just underneath, the movie that it is controlling. (The movie controller is said to be attached to the movie.) In virtually all cases, this results in exactly the appearance for movie w i n d o w s that users expect. But for some purposes, it might be preferable to position the movie controller bar elsewhere. Q u i c k T i m e allows us to do this quite easily. The first thing we need to do is detach the movie controller from the movie. We can do this by calling MCSetControl lerAttached like this: MCSetControl lerAttached(myMC, false) ;
The next thing we need to do is specify the desired new locations of the movie and movie controller bar. Listing 2.5 defines a function, OTUtils_PutControl l erBarOnTop, that places the controller bar above the movie.
Managing the Controller Bar
25
Listing 2.5 Putting the controller bar above a movie. void QTUtils PutControllerBarOnTop (MovieController theMC)
{
i f (theMC == NULL) return; i f (MCIsControllerAttached(theMC) == 1) { Rect myMCRect; Rect myMovieRect; MCGetControl I erBoundsRect (theMC, &myMCRect); myMovieRect = myMCRect; myMCRect.bottom = myMCRect,top + QTUti I s_GetControl I erBarHei ght (theMC) ; myMovieRect, top = myMCRect,bottom + 1; MCSetControl lerAttached(theMC, false) ; MCPositionController(theMC, &myMovieRect, &myMCRect, OL);
Figure 2.3 shows a sample movie w i n d o w after the QTUti l s_PutControll erBarOnTop function has been called on it. In this case, the controller bar is still contiguous to the movie, but it is no longer attached to it. In general, as I've said, it's best to retain the standard appearance of movie windows, with the controller underneath and attached to the window. It is, however, sometimes useful to detach a movie controller from its movie, even if just briefly. Suppose we want to determine the height of the movie controller bar (which, incidentally, we needed to do in Listing 2.5). There is no programming interface for getting this information directly. QuickTime does, however, supply the function MCGetControllerBoundsRect, which returns the rectangle that encloses the movie controller. The only "gotcha" here is that the movie controller rectangle is defined as the rectangle that encloses the movie controller bar and the movie, if the movie controller is attached to the movie; otherwise, if the movie controller is detached from the movie, the movie controller rectangle encloses just the movie controller bar. So, to determine the height of the movie controller bar, we can first detach the controller bar, if it's currently attached, and then retrieve the movie controller rectangle. Listing 2.6 shows our complete function for doing this.
26
Chapter 2 Control
Figure 2.3 A controller bar on top of a movie. Listing 2..6 Finding the height of the controller bar. short QTUti I s GetControl lerBarHeight (MovieControl ler theMC)
{
m
Boolean Rect
wasAttached = false; myRect;
/ / i f the controller bar is attached, detach i t (and remember we did so) i f (MCIsControllerAttached(theMC) == 1) { wasAttached = true; MCSetControl lerAttached(theMC, false) ;
}
/ / get the rectangle of the controller MCGetControl lerBoundsRect (theMC, &myRect); / / now reattach the controller bar, i f i t was o r i g i n a l l y attached i f (wasAttached) MCSetControllerAttached(theMC, true) ; return(myRect.bottom - myRect.top) ;
Managing the Controller Bar
27
Managing Controller Bar Buttons Now that we've played a little bit with the movie controller bar, let's consider how to work with individual buttons in the controller bar. In general, the only thing we can do with the individual buttons is hide and show them. We cannot disable or enable them, and we cannot directly handle clicks on them. The only exception to this concerns the controller bar's custom button; we can intercept and react to clicks on the custom button, as we'll see later in this chapter.
Managing the Standard Controller Buttons Let's begin by considering the standard QuickTime movie controller bar. There are only four buttons that QuickTime allows us to show or hide: the Volume control (sometimes also called the Speaker button), the Step Forward and Step Backward buttons, and the custom button. By default, the Volume control is displayed if and only if the associated movie contains a sound or music track. We can hide the Volume control, if we choose, but we cannot make it visible if the movie does not have a sound or music track. All the other buttons are displayed all the time, unless we programmatically suppress them. We can suppress the display of some of these buttons by manipulating the movie controller's control flags, a 32-bit value whose bits encode the settings of various movie display and playback options. QuickTime defines these constants for showing and hiding buttons in the standard movie controller bar: enum { mcFlagSuppressStepButtons mcFlagSuppressSpeakerButton mcFlagsUseCustomButton
};
=1<<1, = 1<<2,
=1<<5
So, for instance, we can hide the two Step buttons by executing this code: MCDoAction(myMC, mcActionGetFlags, &myControllerFlags) ; MCDoAction(myMC, mcActionSetFlags, (void *) (myControllerFlags I mcFlagSuppressStepButtons));
The idea here is simple: we get the current control flags, set the bit in those flags that suppresses display of the Step buttons, and then send the updated flags back to the movie controller. Naturally, to show a button that's been hidden, we do the opposite; namely, we get the current control flags, clear the appropriate bit in those flags, and then send the updated flags back to the movie controller:
28
Chapter2 Control
MCDoActi on (myMC, mcActi onGetFl ags, &myControlI erFl ags) ; MCDoAction (myMC, mcActionSetFl ags, (void *) (myControl lerFlags & -mcFlagSuppressStepButtons)) ;
One thing to watch out for is that the semantics for the custom button are the reverse of those for the other buttons: setting the flag for the custom button results in that button being displayed, while clearing that flag results in the button being hidden. This is because the custom button is, by default, not displayed.
Managing the QuickTime VR Controller Buttons The QuickTime VR movie controller is more generous than the standard movie controller in that it allows us to show or hide any of the controls in its controller bar (including the Volume control). But this generosity comes at the price of a slight increase in complexity. The simple clearing and setting of bits in the control flags just demonstrated does not always give the desired result. This is because the QuickTime VR movie controller sometimes suppresses buttons even w h e n those buttons have not been explicitly suppressed in the control flags. For example, if a particular QuickTime VR movie does not contain a sound track, then the movie controller automatically suppresses the Volume control. Likewise, if a QuickTime VR movie does contain a sound track, then the Volume control is automatically displayed, again without regard to the actual value of the mcFlagSuppressSpeakerButton flag in the control flags. So far, this behavior is identical to that of the standard movie controller. The main difference between the two controllers is that the QuickTime VR movie controller does provide a way for us to override its default behavior. We might want to do this, for instance, if our application has loaded a sound from a resource or some external file and we'd like to allow the user to adjust the volume of that sound using the Volume control. (Wait a second! Didn't I just say that we can't intercept mouse clicks on the controller bar buttons? If so, then how are we supposed to respond to the user's adjusting the volume using the Volume control? The answer is that we can't directly determine that the user has clicked the Volume control, but we can wait for the movie controller to tell us that the user has changed the volume by looking for movie controller actions of type mcActionSetVolume. So, indirectly, we can accomplish what we want here.) To let us override its default behavior, the QuickTime VR movie controller maintains two sets of flags, a set of control flags (with which we are already familiar) and a set of explicit flags. The explicit flags indicate which bits in the control flags are to be used explicitly (that is, overriding any default behaviors of the movie controller). If a particular bit in the explicit
Managing Controller Bar Buttons
29
flags is set, then the corresponding bit in the control flags is interpreted as the desired setting for that feature. Conversely, if a particular bit in the explicit flags is clear, then the corresponding bit in the control flags is interpreted as it normally is. In this way, the explicit flags operate as a sort of mask for the control bits. To make this clearer, let's consider a concrete example. The QuickTime VR movie controller defines these constants for working with its controller bar buttons: enum { mcFlagQTVRSuppressBackBtn mcFlagQTVRSuppressZoomBtns mcFlagQTVRSuppressHotSpotBtn mcFl agQTVRSuppressTranslateBtn mcFlagQTVRSuppressHelpText mcFlagQTVRSuppressHotSpotNames mcFl agQTVRExpli ci tFl agSet
};
= I L << 1 6 , = I L << 1 7 , = I L << 1 8 , = I L << 1 9 , = I L << 2 0 , = I L << 2 1 , = 1L << 31
If, for example, bit 17 is set in a movie's explicit flags and bit 17 is clear in that movie's control flags, then the zoom buttons are displayed (that is, they are not suppressed). Similarly, if bit 2 is set in a movie's explicit flags and bit 2 is clear in that movie's control flags, then the volume control is displayed, whether or not the movie contains a sound track. There is one final element to this whole story. We need a way of getting and setting a movie controller's explicit flags. Rather than introduce any new movie controller actions, the QuickTime VR engineers decided to use the existing actions (mcActionfietFlags and mcActionSetFlags) but to have those actions operate on the explicit flags or the control flags, depending upon the setting of bit 31 (defined as mcFlagQTVRExplicitFlagSet) in the value passed to MCOoAction. To get or set a bit in a movie's explicit flags, we must set the flag mcF] agQIVRExp] i ci tF] agSet in the parameter we pass to mcActi onGetF] ags or mcActionSetF] ags. To get or set a bit in a movie's control flags, we must clear the flag mcFlagQTVRExplicitFlagSet in the parameter we pass to mcActi onGetFl ags or mcActi onSetFl ags. So let's put this all together and see how we can force the Volume control to be displayed in the controller bar of a QuickTime VR movie that does not contain a sound track. First, we need to get the movie's explicit flags and set the bit in those explicit flags that corresponds to the Volume control: myControl lerFlags = mcFlagQTVRExplicitFlagSet; MCDoActi on (myMC, mcActi onGetFl ags, &myControlI erFl ags) ; MCDoAction(myMC, mcActionSetFlags, (void *) ((myControllerFlags I mcFlagSuppressSpeakerButton) I mcFlagQTVRExplicitFlagSet)) ;
310
Chapter2 Control
Note that w h e n we use the defined constants to set values in the explicit flags, the constant names might be a bit confusing. For instance, setting the bit mcFlagSuppressSpeakerButton in a movie's explicit flags doesn't cause the speaker to be suppressed; it just means: "use the actual value of the mcF1agSuppressSpeakerButton bit in the control flags." Next, we need to set the appropriate bit in the movie's control flags, like this: myControllerFlags = O; MCDoActi on (myMC, mcActi onGetFl ags, &myControlI erFl ags) ; MCDoAction(myMC, mcActionSetFlags, (void *) (myControllerFlags & ~mcFlagSuppressSpeakerButton & -mcFlagQTVRExpli ci tFl agSet)) ;
Once we've executed these six lines of code, the Volume control will appear in the controller bar, w h e t h e r or not the associated QuickTime VR movie has a sound track. Listing 2.7 combines the results of our discussions in this section and the previous section into a single, unified function that we can use to show buttons in a movie controller bar.
Listing 2.7
Showing a button in the controller bar.
void QTUtils ShowControllerButton (MovieController theMC, long theButton)
{
m
l ong
myControl I erFl ags;
/ / handle the custom button separately i f (theButton == mcFlagsUseCustomButton) { MCDoActi on (theMC, mcActi onGetFl ags, &myControlI erFl ags) ; MCDoAction(theMC, mcActionSetFlags, (void *) (myControllerFlags I theButton)) ; } else { / / get the current explicit flags and set the explicit flag for the specified button myControllerFlags = mcFlagQTVRExplicitFlagSet; MCDoAction(theMC, mcActionGetFlags, &myControllerFlags) ; MCDoAction(theMC, mcActionSetFlags, (void *)((myControllerFlags I theButton) I mcFlagQTVRExplicitFlagSet)); / / get the current control flags and clear the suppress flag for the specified button myControllerFlags = O; MCDoAction(theMC, mcActionGetFlags, &myControllerFlags) ; MCDoAction(theMC, mcActionSetFlags, (void *) (myControllerFlags & ~theButton & ~mcFlagQTVRExplicitFlagSet)) ;
Managing Controller Bar Buttons
31
The corresponding function to hide a button in the movie controller bar is exactly parallel; if you're interested, take a look at OIUtils_HideControllerButton in the file OTUti I i t i es. c. Currently, only the QuickTime VR movie controller maintains a separate set of explicit flags and hence knows h o w to interpret the mcF] agQTVRExp] i ci tFlagSet flag. This means that the standard QuickTime movie controller will actually be getting and setting the movie's control flags w h e n we make the calls to get and set the explicit flags. I've written QIUtils_ShowControl lerButton and QTUtils HideControllerButton so that no harm is done if a movie controller does not support any explicit flags.
Using the Controller Bar Custom Button In QuickTime 3, movie controllers gained the ability to display and manage a custom controller bar button. As you can see in Figure 2.4, the custom button is displayed on the right side of the controller bar, just to the left of the grow box.
Figure 2.4 The controller bar's custom button. The button contains a downward-pointing triangle, which is suggestive of the triangle contained in a standard pop-up menu. This is largely because the main intended use of the custom button was to allow the QuickTime plug-in for Web browsers to display a pop-up m e n u of commands. Figure 2.5 shows a typical QuickTime movie embedded in a Web page, with the popup m e n u popped up. The QuickTime public headers and libraries contain everything that we need to put this button to work in our own applications. Let's see how to do that. The first thing we need to do is display the custom button in the controller bar that's attached to our movies. We can use the function QTUtils ShowControllerButton (defined in Listing 2.7) with the constant mcFlagsUseCustomButton to show the custom button, like this: QTUti I s ShowControl I erButton (mcFlagsUseCustomButton) ;
Then, all we need to do is intercept the user's clicks on the custom button and react accordingly. This is a task for our movie controller action filter function. We can add these lines to our ever expanding switch statement in the filter function QXApp_MCActionFilterProc:
32
Chapter 2 Control
case mcActionCustomButtonClick: QTCustom HandleCustomButtonClick(theMC, (EventRecord *)theParams, theRefCon) ; break; So, when the function QTCustom_HandleCustomButtonClick gets called, we know that the user has clicked the custom button in the controller bar. The theParams p a r a m e t e r to our movie controller action filter function points to an event record describing that click. As you can see, w e ' v e cast the theParams p a r a m e t e r to a pointer to an event record and passed it to our clickhandling function. We can now call the M e n u Manager function PopUpMenuSel ect to display a pop-up m e n u at the point specified in the event record. PopUpMenuSelect is very m u c h like the function MenuSelect in that it takes care of drawing the m e n u on the screen, tracking mouse movements within the menu, and then returning to our application an indication of which item (if any) in the m e n u was selected. If you've written any Macintosh applications, you are probably already familiar with MenuSelect, since you've almost certainly used it to handle your application's pull-down m e n u s in the Macintosh m e n u bar. But you might never have used PopUpMenuSelect, since it's called internally by the Control Manager w h e n you handle user actions on pop-up m e n u controls. At any rate, it's just the function we need here.
Figure 2.5 The pop-up menu of the QuickTime browser plug-in.
Using the Controller Bar Custom Button
33
Before we can call PopUpMenuSelect, however, we need to do a little work. First, the point contained in the event record passed to our action filter function is in coordinates that are local to the w i n d o w associated with the movie controller. PopUpMenuSelect wants its input to be in global screen coordinates. So we need to call the LocalToGlobal function to convert from one coordinate system to the other. Second, and more important, we need to get a handle to the m e n u that we want to be popped up at that location on the screen. We can do this in several ways. We could just read the m e n u from a resource file (using the MacGetMenu function), or we could build the m e n u programmatically on the fly (using the NewMenu and AppendMenu functions). To make things easy for the moment, we'll use the latter method and build the m e n u from scratch. The complete QTCustom_HandleCustomButtonClick function is shown in Listing 2.8. Listing 2.8
Handling clicks on the custom button in the controller bar.
void QTCustom HandleCustomButtonClick (MovieController theMC, EventRecord *theEvent, l ong theRefCon)
{
#pragma unused(theMC) MenuHandle Wi ndowObject StringPtr StringPtr StringPtr StringPtr
myMenu = NULL; myWindowObject = NULL; myMenuTitle = QTUtils ConvertCToPascalString(kMenuTitle) myltemlText = QTUtils ConvertCToPascaIString(kltemlText) myltem2Text = QTUtils ConvertCToPascaIString(kltem2Text) myltem3Text = QTUtils ConvertCToPascaIString(kltem3Text)
myWindowObject = (Wi ndowObject) theRefCon; i f (myWindowObject == NULL) goto bai I ; / / make sure we got a valid event i f (theEvent == NULL) goto bai I ; / / create a new menu myMenu = NewMenu(kCustomButtonMenuID, myMenuTitle) ; i f (myMenu ! = NULL) { long myltem = O; Point myPoint; / / add some items to the menu MacAppendMenu(myMenu, myI temlText) ; MacAppendMenu(myMenu, myI tem2Text) ; MacAppendMenu(myMenu, myI tem3Text) ;
34
Chapter 2 Control
; ; ; ;
/ / insert the menu into the menu l i s t MaclnsertMenu(myMenu, hierMenu) ; / / by default, MacAppendMenu enables the item; / / do any desired menu item disabling here i f (! (**myWindowObject).flsDirty) Di sabl eMenuItem(myMenu, kSaveltemlndex) ; / / find the location of the mouse click; / / the top-left corner of the pop-up menu is anchored at this point myPoint = theEvent->where; LocaIToGl obal (&myPoint) ; / / display the pop-up menu and handle the item selected myltem = PopUpMenuSelect(myMenu, myPoint.v, myPoint.h, myltem); switch (MENU_ITEM(myltem)) { case kl temllndex: QTFrame_Beep() ; break; case kl tem2Index. QTFrame_ShowAboutBox() ; break; case kl tem31ndex. QTFrame_UpdateMovieFi I e ( (**myWi ndowObject). fWi ndow) ; break; / / remove the menu from the menu l i s t MacDeleteMenu((**myMenu) .menuID) ; / / dispose of the menu Di sposeMenu(myMenu) ; bail: free (myMenuTi t I e) ; free (myI temlText) ; free (myI tem2Text) ; free (myI tem3Text) ;
}
Figure 2.6 shows the pop-up menu displayed by a call to QTCustom_HandleCustomButtonCl i ck.
Now keep in mind that this is all being accomplished using APIs that belong to QuickTime and to the Macintosh Menu Manager. But the code
Using the Controller Bar Custom Button
35
Figure 2.6 Our application's custom pop-up menu.
we've developed compiles, links, and executes just fine under Windows as well. I find this just simply amazing (but maybe I'm easy to amaze). At the very least, this is one more example of the excellent work done by the engineers who designed and implemented the QuickTime Media Layer (QTML) on Windows, which provides support under Windows for the parts of the Macintosh Operating System and User Interface Toolbox that are used by QuickTime.
S e l e c t i n g an E n t i r e M o v i e You might have noticed, when we were discussing movie editing in the previous chapter, that there are movie controller functions for handling all the standard menu items in the Edit menu, except for the Select All item. To handle that item, we simply called the application-defined function OTUtils SelectAllMovie, which we did not discuss further. It's time to do so now. The linear movie controller supports two actions that are useful here, mcActionSetSelectionBegin and mcActionSetSelectionDuration. To select the
entire movie, as you've probably guessed, we can use mcActi onSetSel ect i onBegin to set the beginning of the movie selection to the beginning of the movie, and then we can use mcActionSetSelectionDuration to set the selection duration to the duration of the entire movie.
The only issue left to consider, then, is how to specify times in a movie. Time management is generally a big concern for multimedia content [as should be clear from the emphasis on time in the product name "Quick-
36
Chapter 2 Control
Time"}. At the most basic level, robust time services are necessary to get a video track to play back at the right speed no matter what the processing speed of the user's computer. They are also necessary to maintain a precise synchronization between sound and video tracks in a movie. QuickTime provides a number of time-related services, so time is something that we'll need to discuss more than once in this book. For the moment, we'll look only at what we need in order to solve the problem at hand. The mcActi onSetSel ect i onBegi n and mcActi onSetSel ect i onOurat i on controller actions both take a parameter of type TimeRecord, which is declared like
this: struct TimeRecord { CompTimeValue TimeScale TimeBase
};
value; scale; base;
A movie's time scale is the number of units that elapse every second. Figuratively speaking, the time scale is the ruler by which the movie is measured. A movie's time scale is set at the time the movie is created and can be determined programmatically using the fietMovieTimeScal e function. Like the distance between markings on a ruler, the number we use for a time scale is somewhat arbitrary. A standard value is 600, which permits nonfractional values for most of the common movie rates {for example, a movie playing at 30 frames per second has 20 units per frame, if the time scale is 600). The values we specify in the value field are interpreted relative to the time scale specified in the scale field. The CompTimeValue structure contains two fields, hi and l o, which specify (respectively) the high- and low-order 32-bits of our time value. To specify the beginning of the movie, we need to set both of these fields to 0. To specify the desired duration of the movie, we can set the lo field to the value returned by the GetMovieDuration function. Luckily, GetMovieDuration returns the length of the specified movie in units relative to the movie's time scale. (The base field is not used here, so we'll set it to 0.) Listing 2.9 defines the function QTUti 1s_SelectA11Movie.
Listing 2.9 Selecting an entire movie. OSErr QTUtiIs SelectAl IMovie (MovieController theMC)
{
TimeRecord Movie ComponentResult
myTimeRecord; myMovie = NULL; myErr = noErr;
i f (theMC : : NULL) return (paramErr) ;
Selecting an Entire Movie
37
myMovie = MCGetMovie(theMC) ; i f (myMovie == NULL) return (paramErr) ; myTimeRecord.value.hi = O; myTimeRecord.value.lo = O; myTimeRecord, base = O; myTimeRecord.scale = GetMovieTimeScale(myMovie) ; myErr = MCDoAction(theMC, mcActionSetSelectionBegin, &myTimeRecord); i f (myErr != noErr) return((OSErr)myErr) ; myTimeRecord.value.hi : O; myTimeRecord.value. Io = GetMovieDuration(myMovie) ; myTimeRecord, base = O; myTimeRecord.scale = GetMovieTimeScale(myMovie) ; myErr = MCDoAction(theMC, mcActionSetSelectionDuration, &myTimeRecord) ; return ((OSErr)myErr) ;
0
Movie User Data A QuickTime movie file contains a list of data, called movie user data, which we can read and manipulate. This list consists of individual items, each of which has an associated type. Some types of user data are predefined by QuickTime, such as the movie's name, copyright information, or author; other types can be defined by specific applications and used for their own purposes. For instance, if we wanted to store the geographical location of a QuickTime VR panorama, we could attach to the movie a piece of movie user data specifying the location's latitude and longitude. A user data item type is a four-character code that looks rather like a resource type. For instance, the movie name user data item has the type ' 9 and the movie copyright user data item has the type ' 9 In addition, there can be more than one user data item of a particular type. If so, those items are distinguished from one another by their index [which starts at 1). To retrieve a movie's user data item of a specific type and index, we first need to call the GetMovieUserData function to get the entire user data list from the movie. GetMovieUserData returns a reference to the user data list; we can pass this reference to any of several other functions that retrieve individual items from the list. For instance, if we know that the item contains text data,
38
Chapter2 Control
we can pass the user data reference to the GetUserDataText function to get that text data. Or, we can pass t h a t reference to the GetUserDataItem function to get any kind of data (including text data) from the user data list. By convention, the predefined types of movie user data are always stored in a bigendian format, so we need to r e m e m b e r to convert the data from bigoendian format to the nativeoendian format w h e n we read the user data; we also need to convert the data from the nativeoendian format to bigoendian format w h e n we write the user data. (See Chapter 12, "2001: A Space Odyssey" for a detailed account of big-endian and nativeoendian data formats.)
Specifying the Controller Type As m e n t i o n e d earlier, any Q u i c k T i m e movie that uses a special movie controller needs to contain a user data item that specifies w h i c h movie controller to use. The type of this user data item is kUserDataMovieControl l erType (defined in the header file Movies.h as 'ctyp'). Listing 2.10 defines the function QTUti I s_GetControl l erType, w h i c h returns the controller type specified in a m o v i e ' s user data, or kUnknownType if no controller type is specified in that user data. Listing 2.10 Getting a movie's controller type. OSType QTUtils GetControllerType (Movie theMovie)
{
UserData OSType OSErr
myUserData= NULL; myType = kUnknownType; myErr = noErr;
/ / make sure we've got a movie i f (theMovie == NULL) return (myType) ; myUserData = GetMovieUserData(theMovie) ; i f (myUserData l= NULL) { myErr = GetUserDataltem(myUserData, &myType, sizeof(myType), kUserDataMovieControl lerType, O) ; i f (myErr == noErr) myType = EndianU32 BtoN(myType);
}
a
return (myType) ;
Movie User Data
39
QTUti 1s_GetControl 1erType just assembles the pieces we've talked about: it calls GetMovieUserData to get the movie's user data list; then it calls GetUserDataItem to retrieve the movie controller type user data item; finally, it converts the big-endian user data to native-endian data using the macro Endi anU32 BtoN. Let's look at a sample use of the QTUtils_GetControl lerType function. Our
basic application framework needs to know whether a movie uses the QuickTime VR movie controller, since the QuickTime VR movie controller does a lot of its own cursor management. When our application starts up, and after it has opened the movie file, it calls the QTUtils_IsQTVRMovie function defined in Listing 2.11 to determine whether the movie is a QuickTime VR movie. As you can see, QTUtils_IsQTVRMovie calls QTUtils_GetControl lerType to determine the movie's controller type and then compares that type against the controller types that we know are used by QuickTime VR movies. (kQTVRQTVRTypeis the controller type of all version 2.0 and later QuickTime VR files, while kQTVRO1dObjectType and kQTVROldPanoType are controller types used by version 1.0 object and panorama movies.)
Listing 2.11
Determining if a movie is a QuickTime VR movie.
Boolean QTUtils IsQTVRMovie (Movie theMovie)
{
Boolean OSType
mylsQTVRMovie = false; myType;
/ / QTVR movies have a special piece of user data identifying the movie controller type myType = QTUti I s GetControl lerType(theMovie) ; i f ((myType == kQTVRQTVRType)II (myType == kQTVROldPanoType)II (myType == kQTVROldObjectType)) mylsQTVRMovie = true; return (myI sQTVRMovi e) ;
It's really just as easy to set a movie's controller type as it is to get a movie's controller type. Instead of calling GetUserOataItem, we need to call SetUserOataItem, as shown in Listing 2.12. Notice that we make sure to convert the type passed to us into big-endian format.
40
Chapter 2 Control
Listing 2.12. Setting a movie's controller type. OSErr QTUtils SetControllerType (Movie theMovie, OSType theType)
{
UserData OSErr
myUserData; myErr = noErr;
/ / make sure we've got a movie i f (theMovie == NULL) return (paramErr) ; / / get the movie's user data l i s t myUserData = GetMovieUserData(theMovie) ; i f (myUserData == NULL) return (paramErr) ; theType = EndianU32 NtoB(theType); myErr = SetUserDataItem(myUserData, &theType, sizeof(theType), kUserDataMovieControl lerType, O) ; m
return (myErr) ;
There are a couple of points to keep in mind here, however. First, the SetUserDataItem function changes only the copy of the movie's user data that's in m e m o r y (and to which myUserData is a reference). If we also want to change the user data stored in the movie file, we need to update the movie file (usually by calling the UpdateMovieResource function). If we were to call QTUti 1s_SetControl lerType to change the movie's controller type and then immediately closed the movie file, the new controller type would not be stored in the movie file. Second, calling QTUti l s_SetControl 1erType does not change the movie controller associated with an open movie, unless we call it before we call NewMovieController. The reason, of course, is that NewMovieController looks at
the movie's user data at the time we call it; any subsequent changes to the movie user data do not automatically change the movie controller assigned to a movie. It occasionally happens that we do want to change a movie's controller type on the fly. To do this, we need to change the movie's user data, close the existing movie controller, and then open a new movie controller. We can accomplish all this by calling the OTUtils_ChangeControllerType function defined in Listing 2.13.
Movie User Data
4'11
Listing 2.13 Changing a movie's controller type dynamically. MovieControl ler QTUtil s ChangeControl lerType (MovieControl ler theMC, OSType theType, long theFl ags) MovieController Movie Rect OSErr
myMC = NULL; myMovie = NULL; myRect; myErr = noErr;
/ / make sure we've got a movie controller i f (theMC =- NULL) return(NULL); / / get the movie associated with that controller myMovie = MCGetMovie(theMC) ; i f (myMovie == NULL) return (NULL) ; GetMovieBox(myMovie, &myRect) ; / / set the new controller type in the movie's user data l i s t myErr = QTUtils SetControllerType(myMovie, theType) ; i f (myErr ! = noErr) return(NULL); / / dispose of the existing controller Di sposeMovi eContro I I er (theMC) ; / / create a new controller of the specified type myMC = NewMovieController(myMovie, &myRect, theFlags) ; return (myMC);
You'll notice that QTUti I s_ChangeControl lerType takes a movie controller, and not a movie, as an input parameter. The reason for this is that we need to use both the movie and the original movie controller within the function and that we can always get the movie currently associated with a movie controller by calling the MCGetMovie function. There is no easy w a y to go in the reverse direction and obtain the movie controller [if any I currently associated with a movie.
42
Chapter 2 Control
M a n i p u l a t i n g a Movie's Looping State Another standard use for movie user data is to specify a movie's looping state. There are three possibilities here. First, a movie can play forward from beginning to end and then stop; a movie like this is said to have no looping. Second, a movie can play forward from beginning to end, and then return to the beginning and play forward again, and so on; a movie like this is said to have normal looping. Finally, a movie can play forward from beginning to end and then play backwards from end to beginning, and then play forward from beginning to end, and so on; a movie like this is said to have palindrome looping. (Go hang a salami; I'm a lasagna hog!) A movie's looping state is specified by a user data item of type 'LOOP'. If the movie doesn't contain an item of this type, then we'll assume that its looping state is no looping. If it does contain an item of this type, then the item data (a long integer) is 0 for normal looping and 1 for palindrome looping. To make our work more readable, let's define three looping state constants: enum { kNormal Loopi ng kPal i ndromeLoopi ng kNoLooping
};
=0, = 1~
=2
Now we can define (in Listing 2.14) a function QTUtils_GetMovieFileLoopingInfo that returns one of these constants, depending on whether it finds a movie user data item of type 'LOOP' and (if there is one) on what the data in that item is. Listing 2.14 Getting a movie's looping state. OSErr QTUtils GetMovieFileLoopinglnfo (Movie theMovie, long *theLooplnfo)
{
UserData long OSErr
myUserData= NULL; myLoopInfo = kNoLooping; myErr = paramErr;
/ / make sure we've got a movie i f (theMovie := NULL) goto bai I ;
Movie User Data
43
/ / get the movie's user data l i s t myUserData = GetMovieUserData(theMovie) ; i f (myUserData l= NULL) { myErr = GetUserDataltem(myUserData, &myLooplnfo, sizeof(myLooplnfo), FOUR CHARCODE('LOOP'), O) ; i f (myErr == noErr) myLooplnfo = EndianS32 BtoN(myLooplnfo);
}
bail: *theLooplnfo = myLooplnfo; return (myErr) ;
W h e n our application opens a movie, it would be nice to set its looping state to the state indicated in its 'LOOP' movie user data item (or indicated by the absence of that item). Happily, the movie controller supports two actions, mcActionSetLooping and mcActionSetLooplsPalindrome, that we can issue to set the looping state to the correct state. The mcActionSetLooping action enables looping of any variety, and the mcActionSetLooplsPalindrome action enables palindrome looping. Listing 2.15 defines a function that we can use to read the looping information from the file and set the appropriate looping state on the specified movie. Listing 2.15 Setting a movie's looping state. OSErr QTUtils SetLoopingStateFromFile (Movie theMovie, MovieController theMC)
{
long OSErr
myLooplnfo = kNoLooping; myErr = noErr;
myErr = QTUti I s GetMovieFileLoopinglnfo(theMovie, &myLooplnfo) ; switch (myLooplnfo) { u
case kNormalLoopi ng: MCDoAction(theMC, mcActionSetLooping, (void *)true); MCDoAction(theMC, mcActionSetLooplsPal indrome, (void *) false) ; break; case kPal indromeLooping: MCDoAction(theMC, mcActionSetLooping, (void *)true); MCDoAction(theMC, mcActionSetLooplsPalindrome, (void *)true) ; break;
414
Chapter 2 Control
case kNoLooping: default: MCDoAction(theMC, mcActionSetLooping, (void *)false); MCDoAction(theMC, mcActionSetLooplsPalindrome, (void *)false) ; break; return (myErr) ;
The final thing we might want to do is store a movie's current looping state in the movie file. We've already seen how to set a movie's controller type (see Listing 2.12), so we might expect to set the looping state in roughly the same manner. However, we cannot just add a 'LOOP' movie user data item with the appropriate data, since the no-looping state is indicated by the absence of such a user data item. What we need to do, therefore, is first remove any existing user data items of type 'LOOP'; then, for normal looping or palindrome looping, we can add a user data item of the appropriate type. It's easy enough to remove all existing items of type 'LOOP" just keep removing the first such item until there are no more remaining, like this: myCount = CountUserDataType(myUserData, FOURCHAR CODE('LOOP')) ; while (myCount--) RemoveUserData(myUserData, FOURCHAR CODE('LOOP'), 1) ; D
m
The complete function for setting a movie's looping state is shown in Listing 2.16. Listing 2.16
Setting the looping state of a movie file.
OSErr QTUtils SetMovieFileLoopinglnfo (Movie theMovie, long theLooplnfo)
{
m
UserData long short OSErr
myUserData= NULL; myLooplnfo; myCount = O; myErr = paramErr;
/ / get the movie's user data myUserData = GetMovieUserData(theMovie) ; i f (myUserData == NULL) goto bai I ;
Movie User Data
45
/ / we want to end up with at most one user data item of type 'LOOP', / / so l e t ' s remove any existing ones myCount = CountUserDataType(myUserData, FOUR_CHAR_CODE('LOOP')); while (myCount--) RemoveUserData(myUserData, FOURCHAR CODE('LOOP'), 1); / / make sure we're writing big-endian data myLooplnfo = EndianU32_NtoB(theLoopInfo) ; switch (theLooplnfo) { case kNormalLooping: case kPal indromeLooping: myErr = SetUserDataltem(myUserData, &myLooplnfo, sizeof(long), FOUR CHARCODE( 'LOOP'), O) ; break; m
n
case kNoLooping" default" myErr = noErr; break; bailreturn (myErr) ;
}
Once again, w e ' d need to make sure to call UpdateMovieResource to update the user data in the movie file or our changes to the user data will be lost w h e n we close the movie.
G e t t i n g a M o v i e ' s S t o r e d W i n d o w Position To finish off our adventures with a movie's user data, let's consider briefly how to get the stored screen position of a movie window. A movie's user data list can contain an item of type 'WLOC', whose accompanying data consists of a 32-bit value that is interpreted as a point that specifies the position of the upper-left corner of the movie window. Listing 2.17 shows the function QTUtils GetWindowPositionFromFile, whose implementation should be completely familiar to you by now.
4G
Chapter2 Control
Listing 2.'17 Getting a movie's stored screen position. OSErr QTUtils GetWindowPositionFromFile (Movie theMovie, Point *thePoint)
{
UserData Point OSErr
myUserData= NULL; myPoint = {kDefaultWindowX, kDefaultWindowY}; myErr = paramErr;
/ / make sure we've got a movie i f (theMovie == NULL) goto bai I ; / / get the movie's user data l i s t myUserData = GetMovieUserData (theMovi e) ; i f (myUserData ! = NULL) { myErr = GetUserDataltem(myUserData, &myPoint, sizeof(Point), FOUR CHAR CODE('WLOC'), O) ; i f (myErr == noErr) { myPoint.v = EndianS16 BtoN(myPoint.v); myPoint.h = EndianS16 BtoN(myPoint.h); m
}
}
m
bail: *thePoint = myPoint; return (myErr) ;
}
In theory, before opening the movie at the window position returned by QTUtils_GetWindowPositionFromFile, we should verify that that position is reasonable for the computer on which the movie is being opened. Otherwise, the new movie window might not be visible. This sanity check is left as an exercise for the reader. Keep in mind that we can look for any of the predefined types of movie user data, and we can define our own types. We'd retrieve our own custom types of user data items in exactly the same way that we've retrieved the types defined by QuickTime. The only restriction is that Apple has reserved for itself all four-character types that consist solely of lowercase letters and special characters. So, for instance, we shouldn't use ' b i l l ' as a custom user data type, but we're free to use 'BILL' or 'Bill '. I know what you're thinking: what about 'WLOC'and 'LOOP'? Shouldn't they instead be 'wloc' and 'loop', to fit within Apple's reserved types? Indeed, they should be, if they were predefined user data types. But they aren't; we
Movie User Data
47
w o n ' t find 'WLOCi or 'LOOP' defined in any QuickTime header file. Rather, these types were used as custom types early on in QuickTime's history by the application MoviePlayer. Other applications followed suit, and these two types have become accepted ways of saving a movie's location and looping state.
Opening URLs Let's finish up with something completely cool and incredibly easy to do. Namely, let's have our application tell the user's default Web b r o w s e r to open a Web page in a browser window. There are quite a few reasons you might want to do this. For one, your application might have a Help m e n u item {or perhaps a button in your About box) to send the user to your own website, so that you can provide up-to-date information about your product. Or, you might detect that the user's machine is lacking a d e c o m p r e s s o r needed for some data in the movies you want to play, so you w a n t the user to download the necessary files. For whatever reason, it's just plain useful to have at your disposal an easy w a y to open a Web browser and display a given URL. How easy can this be? Well, assuming that myMCis an open movie controller and that myHandle is a handle to a block of m e m o r y that contains a nullterminated string representing the URL, it's just this easy: MCDoAction(myMC, mcActionLinkToURL, (void *)myHandle) ;
That's right, with one line of code, w e ' v e instructed the movie controller to launch the user's default Web b r o w s e r {if it isn't already open) and display the specified URL in a new window. Of course, there is u n d o u b t e d l y some more code required to get the URL into a handle [supposing that it began its life as a typical C string of type char *). And, as w e ' v e seen, t h e r e ' s a fair a m o u n t of code r e q u i r e d to open a movie and associate a movie controller with it. But once we've done all that work, it's nice to know that we can leverage it to good effect. But you might be wondering: w h a t if we don't have a movie controller at hand? {Maybe we don't have any movie windows open yet.) W h a t do we do then? Well, we can simply open a movie controller. As I mentioned earlier, a movie controller is a software component that manages a user's interaction with a movie. Accordingly, we can use the Component Manager to open a movie controller, w h e t h e r or not we have a movie to attach it to. To do this, we just call the Component Manager's OpenADefaultComponent function and specify that we want an instance of a component of type MovieControllerComponentType. Listing 2.18 shows the complete function that takes a C string
48
Chapter2 Control
specifying a URL and does all the work necessary to open the specified URL in the user's default Web browser.
Listing 2.18 Opening a URL. OSErr QTApp_HaveBrowserOpenURL (char *theURL)
{
MovieController Handle Size OSErr
myMC = NULL; myHandl e = NULL; mySize = O; myErr = noErr;
/ / copy the specified URL into a handle mySize = (Size)strlen(theURL) + i ; i f (mySize == O) goto bai I ; / / allocate a new handle myHandle = NewHandleClear(mySize) ; i f (myHandle == NULL) goto bai I ; / / copy the URL into the handle BlockMove(theURL, *myHandle, mySize) ; / / instantiate a movie controller and send i t an mcActionLinkToURL message myErr = OpenADefaultComponent(MovieControl I erComponentType, O, &myMC); i f (myErr ! = noErr) goto bai I ; myErr = MCDoAction(myMC, mcActionLinkToURL, (void *)myHandle); bail 9 i f (myHandle i= NULL) Di sposeHandl e (myHandle) ; if
(myMC != NULL) C1oseComponent(myMC) ;
return (myErr) ;
Opening URLs
49
This is a generally useful technique to add to our bag of tricks: if there's a movie controller action that w e ' d like to issue but we don't have a movie controller close at hand, we can just call OpenADefau]tComponent to get a movie controller, issue the action, and then dispose of the controller. Movie controllers don't actually have to be controlling movies for us to put t h e m to work.
Conclusion After all this discussion of movie controllers and the things we can do with them, you might be wondering w h e t h e r it's possible to play back movies without the assistance of a movie controller. In other words, do we always have to have a movie controller lurking around somewhere? The answer is, yes and no. Some types of QuickTime movies require a movie controller while others do not. Standard linear QuickTime movies can be played back without the assistance of a movie controller, but of course you'll have to do a whole lot of work to replicate the user interaction normally provided by the movie controller. Other types of QuickTime movies, such as QuickTime VR and wired sprite movies, must have a movie controller associated with them. What's distinctive about the types of QuickTime movies that require movie controllers is that they are by nature highly interactive. You don't just sit back and watch a QuickTime VR movie; instead, you actively navigate within the node and within the multinode scene. The same is true for wired sprite movies: by and large, the real impact of a wired sprite movie arises from actions the user performs with the mouse. This isn't to deny that you could construct a QuickTime VR movie that navigated itself, sort of like a guided tour through a house or m u s e u m , which therefore was minimally interactive. But you couldn't manage the self-navigation without a movie controller. Still, some kinds of movies can be played back ~ la carte, as it were, without the assistance of a movie controller. In the next chapter, we'll take a look at how to use QuickTime's Movie Toolbox to do this.
50
Chapter2 Control
Out of Control
Introduction In the previous two chapters, we've focused almost exclusively on playing QuickTime movies using movie controllers. This is by far the easiest way to manage movies and to support the standard types of user interaction with movies. Indeed, some types of QuickTime movies cannot be presented to or managed by the user without a movie controller. But there are other types of QuickTime movies (most notably, standard linear movies) that can be played back without using a movie controller. In this chapter, we'll see how to accomplish this. In effect, our goal will be to provide all the capabilities that are provided by our basic application QTShell--for linear movies at least-but without the assistance of movie controllers. We'll show how to start and stop movies, provide basic editing services, and set various looping states. Why might we want to do this? Well, there are situations in which you want to play QuickTime movies but don't necessarily want the user to be able to manipulate those movies in the ways typically afforded by movie controllers. Perhaps the simplest example of this is found quite often in games, in which the application plays what's called a cut movie or a c u t s c e n e when the user completes one level and advances to the next. The cut movie serves as a transition from one level to the next, and you generally don't want the user interrupting or {heaven forbid!) editing your cut movie. So using the full-fledged movie controller interface is perhaps not the best way to handle QuickTime movie playback here. There are also more complicated examples of using controllerless QuickTime movies. For instance, we might want to use a linear QuickTime movie as a texture for a 3D object that's being displayed by our application. Figure 3.1 shows a window of the application TextureEyes, which uses QuickDraw 3D to define and render three-dimensional objects. In this window, we've created a cube and set its surface texture to be a QuickTime movie.
51
Figure 3.1
A QuickTime movie used as a texture on a 3D object.
Similarly, we might want to embed a QuickTime movie within another QuickTime movie. For instance, QuickTime VR allows us to draw into a panoramic node. We can use this capability to draw the individual frames of a QuickTime movie into a panorama, as shown in Figure 3.2. Here, the toy train on the table isn't part of the original panorama. Rather, we're drawing the frames of a standard QuickTime movie (one of whose frames is shown in Figure 3.3) into the panorama, using the QuickTime VR application programming interfaces and some QuickDraw routines to drop out the black background. The net effect is that the train appears to travel in a circle on the table, thereby imparting some motion and sound to the otherwise static and silent panorama. We might also want to embed a linear QuickTime movie into another linear QuickTime movie, as shown in Figure 3.4. The point is not that we couldn't have used movie controllers to help us display and manage the cut scenes or the textured or embedded QuickTime movies in these sorts of cases. Rather, the point is that we don't need to do so. In the examples we've mentioned, we just need a way to manage the display of the movie frames at the appropriate time (and to play back the movie's sound track, if it has one). So in those cases, the only services we really need are QuickTime's imaging, sound-producing, and timing services. We don't need the robust user interaction services provided by the standard linear movie controller.
52
Chapter 3 Out of Control
Figure 3.2
A QuickTime movie embedded into a QuickTime VR panorama.
Figure 3.3
The QuickTime movie embedded in Figure 3.2.
It's really a question of levels: the movie controller interface for controlling movies is a higher-level interface than what we need to accomplish the previously outlined tasks. Now we'll drop down a level and directly use the services of that part of QuickTime known as the Movie Toolbox. The Movie Toolbox is really the heart and soul of QuickTime. It provides services for opening movie files and extracting movies from them, playing movies, editing movies, creating movies, and much more. To a large degree, programming with QuickTime is using the Movie Toolbox.
Introduction
53
Figure 3.4 A QuickTime movie embedded into a QuickTime movie.
Figure 3.5
A movie window displayed by QTMooVToolbox.
So here's what we want to accomplish in this chapter: we want to modify our basic application QTShell so that it can open and play back linear QuickTime movies without using movie controllers. Let's call this new application QTMooVToolbox, in honor of the fact that we'll be doing everything using the Movie Toolbox. Since we're not using a movie controller, there will be no movie controller bar in our movie windows. A typical movie window will therefore look like the one in Figure 3.5. 54
Chapter 3 Out of Control
Figure 3.6 The Test menu for QTMooVToolbox.
As indicated, we want to support the standard movie editing capabilities, so our application's Edit m e n u will be unchanged {though, of course, the code providing the editing capabilities will change quite a bit}. We also want to provide the user with a way to start and stop the movie and to set normal and palindrome looping. Figure 3.6 shows the Test m e n u that we want to support. The last m e n u item here (Add Picture In Picture) is particularly interesting. It allows us to embed one linear QuickTime movie inside of another linear QuickTime movie {as shown in Figure 3.4}. As we'll see, it's fairly easy to use the Movie Toolbox to accomplish this.
Getting Started Setting Up to Use QuickTime Before moving forward with our QTMooVToolbox application, we need to back up a step or two to fill in a few details that we skipped over in the first two chapters. In order to use any of the Q u i c k T i m e services, we need to m a k e sure that the Q u i c k T i m e client s o f t w a r e is available on the target machine. On W i n d o w s computers, we can do this by trying to initialize the QuickTime Media Layer, like this: myErr = InitializeQTML(OL);
If I n i t i a l izeQTML completes successfully {that is, if myErr is noErr), then we k n o w that Q u i c k T i m e is available. On the o t h e r hand, if InitializeQTML doesn't complete successfully, then either QuickTime or some other essential c o m p o n e n t is missing, in w h i c h case we will just exit the application {perhaps after informing the user that QuickTime needs to be installed}. On Macintosh computers, we can call the Gestalt function to determine w h e t h e r QuickTime is available, as shown in Listing 3.1:
Getting Started
55
Listing 3.1 Determining whether QuickTime is available. Boolean QTUtils IsQuickTimelnstalled (void)
(
w
long OSErr
myAttrs; myErr = noErr;
myErr = Gestalt(gestaltQuickTime, &myAttrs) ; return(myErr == noErr) ;
On either Windows or Macintosh computers, once we've determined that QuickTime is indeed available in the current operating environment, we need to call the EnterMovies function, like so: myErr = EnterMovies(); EnterMovies initializes the Movie Toolbox, p e r f o r m i n g any necessary setup for our application (such as allocating any private storage it might need to use on our behalf). As with I n i t i a l izeQTML, we will check the value returned by EnterMovies and exit the application if an error occurs. When we are finished using QuickTime services--usually, w h e n our application is about to terminate--we should undo the work done by EnterMovies and (on Windows) InitializeQTML. We can call the ExitMovies function to terminate our connection with the Movie Toolbox. On Windows, we also need to call TerminateQTML to unregister our application from the QuickTime Media Layer.
Using Application-Specific Data Suppose now that our application is up and running, that we've successfully initialized QuickTime and the Movie Toolbox, and that the user has decided to open a movie file {perhaps using the Open c o m m a n d in the File menu). Our basic cross-platform framework calls the OTFrame_OpenMovielnWindow function to prompt the user for the movie file to open, create a w i n d o w object record to hold basic information about the movie and the file it is contained in, open a new w i n d o w on the screen, adjust the size of that w i n d o w to fit the movie's natural size, and do some other useful setup before the user can begin to interact with the movie. QTFrame_OpenMovielnWindow also calls the function OTApp_SetupWindowObject,
defined in the file ComApplication.c, to allow our application to perform any application-specific actions on the new movie before it is displayed to the user. Both of our previous applications (namely, QTShell and QTController) have
56
Chapter3 Out of Control
not put any code at all into QTApp_SetupWindowObject because the default con-
figuration was sufficient for our purposes then. Here, for QTMooVToolbox, we'll need to change that, for two reasons. First, we need to maintain some information for each open movie window beyond what is contained in the window object record. Second, since we are not using movie controllers in the QTMooVToolbox application, we need to do some additional work to prepare our movies for playback. Let's tackle the first task here and defer the second until a bit later in this chapter. We already have the apparatus in place to support adding applicationspecific data to our movie windows. As you may recall, the window object record includes the field fAppData, which is declared to be of type Handle. We put this field there precisely to provide ourselves a place to store any information that is specific to a particular application {since we don't want to be changing the framework files all the time). For QTMooVToolbox, we'll define a structure of type Appl icationDataRecord that contains three fields: typedef struct ApplicationDataRecord { MovieEditState fMovieEditState; / / the edit state of the movie Movie fPIPMovie; / / the picture-in-picture movie Rect fPIPRect; / / the picture-in-picture rectangle } Appl icationDataRecord, *Appl icationDataPtr, **Appl icationDataHdl ;
We don't need to explain these fields quite yet (although the comments should give you a reasonable idea of what they are for). But we do need to show how the application data record gets created and attached to the window object. We do this in the function QTApp_SetupWindow0bject defined in Listing 3.2. Listing 3.2 Setting up a window object. void QTApp_SetupWindowObject (WindowObject theWindowObject)
{
Movie ApplicationDataHdl OSErr
myMovie = NULL; myAppData = NULL; myErr = noErr;
i f (theWindowObject l: NULL) { / / get rid of the movie controller that's already been attached to this window object; / / we do this to illustrate how to manage movies without using a movie controller i f ((**theWindowObject).fController ! = NULL) { MCSetActionFi IterWithRefCon( (**theWindowObject). fControl ler, NULL, OL) ; Di sposeMovieControl I er( (**theWi ndowObject). fControl I er) ; (**theWindowObject) .fControl ler = NULL;
}
Getting Started
57
/ / allocate an application-specific data record myAppData = (ApplicationDataHdl )NewHandleClear(sizeof(Appl icationDataRecord)) ; (**theWi ndowObject), fAppData = (Handle)myAppData; i f (myAppData ! = NULL) { (**myAppData).fMovieEditState = NULL; (**myAppData).fPIPMovie = NULL; MacSetRect(&(**myAppData).fPIPRect, O, O, O, 0);
}
/ / some lines omitted here
Notice that the first thing we do in QTApp_SetupWindowObject is get rid of the movie controller that has already been created by the time QTApp_SetupWindowObject is called. That's because (as you already know) we want to illustrate how to manage movies without using a movie controller. We might as well just dispose of the controller, so we're sure it's not doing any w o r k for us. The second thing we do in OTApp_SetupWindowObject is call NewHandleClear to allocate an application data record and initialize its fields. (Of course, the initialization here is overkill, since NewHandleClear zeros the bytes in the newly allocated block; nevertheless, it's useful to make this initialization explicit.) Then we set the fAppOata field of the w i n d o w object passed to QTApp_SetupWindowObject to the newly allocated handle. This allows us, as we intended, to keep a copy of this record for each movie window. The file ComFramework.c defines a couple of functions that facilitate retrieving the application-specific data attached to a movie. For instance, we can use the function OTFrame_GetAppOataFromWindowObject, defined in Listing 3.3, to retrieve the application-specific data associated with a w i n d o w object.
Listing 3.3 Getting the application-specific data attached to a window object. Handle QTFrame_GetAppDataFromWindowObject (Wi ndowObject theWindowObject)
{
/ / make sure this is a window object belonging to our application i f ( !QTFrame_IsWindowObjectOurs (theWi ndowObject) ) return(NULL) ; return ( (**t heWindowObject). fAppData) ;
Similarly, we can use the function QTFrame_GetAppDataFromWindow, defined in Listing 3.4, to retrieve the application-specific data attached to a particular movie window.
58
Chapter 3 Out of Control
Listing 3.4 Getting the application-specific data attached to a movie window. Handl e QTFrame_GetAppDataFromWindow (Wi ndowReference theWi ndow)
{
WindowObject
myWindowObject = NULL;
myWindowObject = QTFrame_GetWindowObjectFromWi ndow(theWi ndow) ; i f (myWindowObject == NULL) return(NULL); return (QTFrame_GetAppDataFromWi ndowObject (myWindowObject) ) ;
We'll use these functions extensively throughout the rest of this chapter.
Updating the Application Framework The basic framework for playing QuickTime movies that we've used for the QTShell and QTController sample applications makes extensive use of movie controller components to manage the movie playback and any user interaction with the movie. It uses movie controllers to help set the window size, handle movie editing, process movie-related events, and do a handful of other important tasks. So, I must admit that I was more than a little worried when I set about to develop the QTMooVToolbox application for this chapter. After all, the very first application-specific thing we do (in Listing 3.2) is throw away the movie controller that the framework so kindly created and configured for us. How much of the entire framework was dependent upon work done by that movie controller? Or, asked another way, how much of the basic QTShell framework would we need to rewrite in order to play back movies using only the Movie Toolbox? Surprisingly, very little had to change. In fact, only three functions needed reworking to handle the new assumption that the movie window might no longer have a movie controller associated with it. First of all, the OTFrame_Si zeWindowToMovie function originally contained these lines: myMC = (**theWindowObject).fController; myMovie = (**theWindowObject).fMovie; i f (MCGetVisible(myMC)) MCGetControl I erBoundsRect (myMC, &myMovieBounds) ; else GetMovi eBox(myMovie, &myMovieBounds) ;
This just says" if the movie has a visible movie controller bar, then get the desired window size by calling MCfietControl 1erBoundsRect (which returns the
Getting Started
59
rectangle that encloses the movie and the movie controller bar); otherwise, call GetMovieBox (which returns the rectangle that encloses just the movie). To allow for the case w h e r e t h e r e is no m o v i e c o n t r o l l e r at all, w e can rewrite the key lines like this: GetMovieBox(myMovie, &myMovieBounds) ; i f (myMC i= NULL) i f (MCGetVisible(myMC)) MCGetControl I erBoundsRect(myMC, &myMovieBounds) ;
Second, the framework function QTFrame_HandleEditMenultem also assumed that every movie window had a movie controller associated with it, in which case it could use movie controller functions like MCCut and MCCopy to handle the Edit m e n u items. In QTMooVToolbox, this is no longer true, so we need to provide a way for an application to intercept the Edit m e n u c o m m a n d s and do its own type of movie editing. We can do this very simply by inserting a call to OTApp_HandleMenu before OTFrame_HandleEditMenultem handles the menu items. If QTApp_HandleMenu returns the value true to indicate that it has handled the m e n u item, then we just skip the rest of QTFrame_Handl eEdi tMenuItem. We'll see later in this chapter how our application actually handles the Edit menu items; for the moment, at least we have successfully provided a way to prevent the framework from trying to handle Edit m e n u items using movie controller functions. The last important change we need to make to our basic framework is to provide a way for both our Macintosh and Windows applications to tell the Movie Toolbox to play any movies that are open. When we're using QuickTime, we don't just start a movie playing and then forget about it, expecting perhaps that it will play through until the end and then stop. Instead, from time to time, we need to explicitly allocate some processor time to the Movie Toolbox so that it can do whatever it needs to do in order to keep the movie playing. This periodic allocation of processor time to the Movie Toolbox is k n o w n as tasking a movie, and we can accomplish it by calling the MoviesTask function over and over until the movie is done playing. So w h a t we need to do now is provide a way for QTMooVToolbox to call MoviesTask periodically. (When we are using movie controllers, we never need to call MoviesTask because the MCIsPlayerEvent function calls it internally for us.) A standard way to do this on the Macintosh is to insert a call to MoviesTask in the application's main event loop. For several reasons (which we don't need to go into), we'll adopt a slightly different technique in QTMooVToolbox; we'll call MoviesTask in response to null events (which occur often enough to keep the movie playing smoothly). For Windows applications, however, this is slightly trickier, since there is no Windows equivalent of the Macintosh null or idle event (and there is no main event loop). Probably the
60
Chapter3 Out of Control
best solution for Windows applications would be to install a timer that calls MoviesTask periodically. For the moment, however, we'll adopt a different (and much simpler) approach. Our basic Windows framework already calls the function OTApp_HandleEvent every time a movie window receives a message to process. So we'll just look for null events generated by QTML there and call QTApp_Iclle (which in turn calls MoviesTask) for every open movie window. Listing 3.5 shows the changes we can make to QTApp_HandleEvent to keep our Windows movies running smoothly.
Listing 3.5 Getting Windows applications to call QTApp_ldle. Boolean QTApp_HandleEvent (EventRecord *theEvent)
(
Boolean
mylsHandled = fal se;
# i f TARGET OS WIN32 WindowReference m
myWindow = NULL;
i f (theEvent I= NULL) i f (theEvent->what == nullEvent) { myWindow = QTFrame_GetFrontMovieWi ndow() ; while (myWindow ! = NULL) { QTApp_Idl e (myWindow) ; myWindow = QTFrame_GetNextMovieWi ndow(myWindow) ;
}
}
#endif return (mylsHandl ed) ;
Keep in mind that these strategies might not work for more complicated or more specialized applications. On the Macintosh, for instance, an application might be doing so much processing that there are not enough null events generated to keep the movie playing smoothly. Conversely, our Windows strategy might consume too much processor time with its almost constant calls to QTApp_Idle. So QTMooVToolbox most certainly does not provide a universal solution to the problem of when and how to call MoviesTask. The strategies that we've adopted here are designed only to keep the movies running smoothly, with a minimum of changes to our basic QuickTime framework.
Getting Started
61
Preparing Movies for Playback So far, our application can open QuickTime movie files, read the movies from those files, and create appropriately sized windows to hold those movies. Are we finally ready to begin playing the movies? In other words, w h e n the user indicates that he or she wants the movie to begin playing, can we just start the ball rolling by calling the StartMovie function and then let our framework task the movie periodically? The answer here is, yes and no. We could, indeed, just call StartMovie, and most movies would start playing pretty much immediately, as desired. Other movies might require a small but noticeable amount of time to perform some necessary setup activities, such as allocating buffers to hold data from the movie file and setting up various QuickTime components to handle the process of decompressing the data in the file. This setup is unavoidable; however, if our application doesn't start the movie playing immediately, we can perform this setup right after the user opens the movie and before the user actually starts playing the movie so that it is effectively unnoticeable. This process is called prerolling the movie. For some movies--in particular, for streamed movies located remotely on the Web or on file servers--prerolling alone is not sufficient to guarantee an optimal user experience. That's because some actions need to occur even before the movie can successfully be prerolled. QuickTime needs to set up connections to the remote servers and negotiate one or more protocols for exchanging data; it also needs to get information about the types of data in those remote movies. This process is called preprerolling the movie {because it needs to occur prior to the prerolling process}. Unless we prepreroll movies stored remotely, the movie playback would be annoyingly choppy, and some of the data in those movies (for instance, the sound} might not play correctly at all. So we need a more general method of starting up movies that will accommodate both local and remote QuickTime movies. We need to prepreroll and preroll our movies. Let's consider these operations in reverse order.
Prerolling Movies To preroll a movie, we can use the Movie Toolbox function Prerol IMovie. As indicated, PrerollMovie does whatever it can to prepare the movie for immediate playback once the movie is started. This involves determining w h a t kinds of data are in the movie and setting up the appropriate software components to handle those kinds of data. Prerolling might also involve actually reading some of the movie's data and getting the relevant decompressors ready to decompress that data. Because of this, PrerollMovie needs to know the current location in the movie and the rate at which the movie is to be played. We can get the current location in the movie by calling GetMovieTime,
G2
Chapter3 Out of Control
and we can get the m o v i e ' s default p l a y b a c k rate by calling GetMoviePreferredRate. So we can preroll a movie by executing these lines of code: myTimeValue = GetMovieTime(myMovie, NULL); myPl ayRate = GetMoviePreferredRate (myMovie) ; PrerolIMovie(myMovie, myTimeValue, myPlayRate) ;
If for some reason you want to change the current location in the movie or the movie's default playback rate, you should do it before calling Prerol 1Movie so that you don't invalidate the work done by PrerollMovie. You can set the current location in the movie by calling SetMovieTime, and you can set the default playback rate by calling SetMovi ePreferredRate. The default playback rate is the rate that StartMovie uses w h e n it starts a movie playing. When you open a movie from a movie file, the actual playback rate is 0 (that is, the movie is not playing).
Preprerolling Movies To prepreroll a movie, we can use the Movie Toolbox function PrePrerol l Movie, which establishes any required network connections between the computer running our application and the computer that contains the movie being preprerolled. If the movie resides on the same computer as the application (that is, if the movie is a local movie), then PrePrerol 1Movie has nothing to do and it returns immediately. As a result, there is no harm in calling PrePrerol IMovie for every movie our application opens. On the other hand, if the movie being preprerolled is not a local movie, then preprerolling it can take a significant amount of time, particularly if the local computer needs to access the remote computer over a dialup line. To keep your application from stalling while QuickTime negotiates a connection with the remote computer, you can call PrePrerollMovie asynchronously, in which case PrePrerollMovie returns almost immediately and then executes an application-defined completion function w h e n the preprerolling is finished. PrePrerollMovie has the same calling interface as PrerollMovie, except that you must also specify a movie preprerolling completion routine and an optional reference constant that is passed to the completion routine" myPl ayRate = GetMoviePreferredRate (myMovie) ; PrePrerolIMovie(myMovie, O, myPlayRate, gMoviePPRollCompleteProc, (void *)theWindowObject) ;
Here, gMoviePPRollCompleteProc is a universal procedure pointer (UPP)to the movie preprerolling completion routine. QTMooVToolbox allocates this UPP w h e n it starts up, in the function QTMT_Init defined in Listing 3.6.
Preparing Movies for Playback
G3
Listing 3.6 Allocating a routine descriptor for QTMT_MoviePrePrerollCompleteProc. void QTMT_Init (void)
(
}
/ / allocate a routine descriptor for our prepreroll completion routine gMovi ePPRol I CompleteProc = NewMoviePrePrerol l CompleteProc ( QTMT_MoviePrePrerol I CompleteProc) ;
When the preprerolling is complete, the Movie Toolbox executes our movie preprerolling completion function, defined in Listing 3.7.
Listing 3.7 Respondingwhen a movie is done preprerolling. PASCAL_RTN void QTMT_MoviePrePrerol l CompleteProc (Movie theMovie, OSErr thePrerolIErr, void *theRefCon)
{
#pragma unused(thePrerol l Err) WindowObject Appl icationDataHdl TimeValue Fixed
myWindowObject = (Wi ndowObject) theRefCon; myAppData = NULL; myTimeVal ue; myPl ayRate;
myAppData = (Appl i cat i onDataHdl ) QTFrame_GetAppDataFromWi ndowObject (myWindowObject) ; i f ((theMovie == NULL)II (myWindowObject == NULL)II (myAppData == NULL)) return; / / preroll the movie, so that i t ' s ready to play when we call StartMovie myTimeValue = GetMovieTime(theMovie, NULL); myPl ayRate = GetMoviePreferredRate(theMovie) ; PrerolIMovie(theMovie, myTimeValue, myPlayRate) ; / / for the picture-in-picture movie, start i t playing in a loop i f (theMovie == (**myAppData).fPIPMovie) { QTMT_SetMovieLoopState(theMovie, kNormalLooping) ; StartMovi e(theMovie) ;
}
As you can see, our movie preprerolling completion function is quite simple. It really just prerolls the movie, thereby making the movie ready for playback. For some movies (namely, for QTMooVToolbox's "picture-in-
64
Chapter 3 Out of Control
picture movies"), it also starts the movies playing in a loop. We'll discuss picture-in-picture movies later. Note that preprerolling and prerolling are required only for movies that we are managing directly, using the Movie Toolbox. If we use the movie controller interface for managing movies, the movie controller automatically preprerolls and prerolls the movies for us.
Playing Movies Now we are finally ready to start our movie playing. Assuming that a movie has already been preprerolled and prerolled, we can set it in motion by setting its rate to a nonzero value, using the SetMovieRate function. Or, we can simply call the StartMovie function, which sets the movie rate to the default {or "preferred") movie rate. QTMooVToolbox defines the function QTMT_ StartMovie (shown in Listing 3.8) to start a movie. Listing 3.8 Starting a movie playing. void QTMT_StartMovie (Movie theMovie)
{
i f (theMovie == NULL) return; / / i f we aren't looping and we're at the end of the movie, / / return to the beginning of the movie i f (!QTMT_IsMovieLooping(theMovie)) i f (GetMovieTime(theMovie, NULL) == GetMovieDuration(theMovie)) GoToBeginni ngOfMovie(theMovi e) ; StartMovi e(theMovi e) ;
QTMT_StartMovie checks to see whether a nonlooping movie has reached its end; if it has, QTMT_StartMovie calls the Movie Toolbox function GoToBeginningOfMovie to reset the current movie time to the beginning of the movie. If we had been playing the movie using a movie controller, the movie controller would have done this for us. Since we're programming at a slightly lower level, we need to do some of this housekeeping ourselves. Similarly, w h e n we are playing a nonlooping movie using the Movie Toolbox and the movie reaches its end, its rate is not automatically set to O. Again, this is some minor housekeeping that we need to take care of ourselves. In this case, we'll do the appropriate check in our QTApp_Idl e routine, defined in Listing 3.9.
Playing Movies
65
Listing 3.9 Performing idle-time tasks. void QTApp_Idle (WindowReference theWindow)
{
GrafPtr WindowObject ApplicationDataHdl
mySavedPort; myWindowObject = NULL; myAppData = NULL;
GetPort (&mySavedPort) ; MacSetPort (QTFrame_GetPort FromWindowReference(theWi ndow)) ; myWindowObject = QTFrame GetWindowObjectFromWindow(theWi ndow) ; myAppData = (AppI i cat i onDataHdl ) QTFrame_GetAppDataFromWi ndow(theWi ndow) ; i f ((myWindowObject I= NULL) && (myAppData ! = NULL)) { i f (!QTMT_IsMovieLooping ( (**myWi ndowObject), fMovie)) i f (GetMovieTime((**myWindowObject).fMovie, NULL) == GetMovi eDurat i on ( (**myWi ndowObject). fMovi e) ) i f (GetMovieRate((**myWindowObject). fMovie) > O) SetMovieRate((**myWindowObject). fMovie, O) ; i f ((**myWindowObject).fMovie ! = NULL) MoviesTask((**myWindowObject). fMovie, DoTheRightThing) ; i f ((**myAppData).fPIPMovie I= NULL) QTMT_DrawPicture I nPi ctureMovi e (myWindowObject) ; MacSetPort (mySavedPort) ;
QTApp_Idle does three main things. It sets the movie rate of the movie in the specified window to 0 if it isn't looping and it has played to its end; it tasks the movie; and it draws any picture-in-picture movie in the specified window. (Once again, we'll discuss picture-in-picture movies at more length later.) As you can see, MoviesTask takes two parameters; these are the movie to be tasked and a maximum number of milliseconds that MoviesTask should spend doing its work. Movies.h defines the constant DoTheRightThing as 0, which means to service the specified movie once and then return. So, at last, we have at hand all the essential elements of playing movies using the Movie Toolbox. First, we open a movie file and load the movie from it (using the same code that we used w h e n playing movies using movie controllers). Then, we prepreroll and preroll that movie. Then, we start the movie playing by calling StartMovie. And finally, we periodically call MoviesTask to give the movie some time to play. It's OK to call MoviesTask on a
66
Chapter 3 Out of Control
movie that has finished playing, so in QTApp_Idle we don't bother to check w h e t h e r the movie is actually playing or not. In fact, we shouldn't make that check, since we need to call MoviesTask on a movie while it is preprerolling as well as while it is playing.
Editing Movies Editing movies is one of the tasks at w h i c h movie controllers excel. A movie c o n t r o l l e r k e e p s t r a c k of a m o v i e ' s c u r r e n t s e l e c t i o n a n d allows us (for instance) to cut that selection from that movie by calling the function MCCut, like this" case IDM EDITCUT: myEdi tMovi e = MCCut(myMC) ; break; m
As you can see, MCCut also returns to us a movie that is the cut selection, which we can put on the scrap {to make it available for subsequent pasting) by calling PutMovie0nScrap. Moreover, the movie controller keeps track of the current edit state of the movie that exists before each editing operation, so that it can restore that state if we subsequently call MCUndo. A movie's current edit state consists of all the information that describes the movie's contents, such as the sound and video data in the movie; the current edit state also includes the movie's current selection. The Movie Toolbox provides a set of high-level movie editing functions, which are just as easy to use as the functions provided by movie controllers. For instance, to cut the current movie selection, we can call the CutMovieSelect i on function. case IDM EDITCUT" myEditMovie = CutMovieSelection(myMovie) ; break;
Similarly, we can use the ClearMovieSelection function to clear the c u r r e n t movie selection (that is, r e m o v e it f r o m the movie w i t h o u t r e t a i n i n g the removed data). case IDM EDITCLEAR. Cl earMovi eSel ecti on (myMovi e) ; break; m
Moreover, the Movie Toolbox provides the SetMovieSelection function, which we can use to handle the Select All m e n u item in the Edit menu, like this"
Editing Movies
67
case IDM EDITSELECTALL" SetMovieSelection(myMovie, OL, GetMovieDuration(myMovie)) ; break;
There is one complication here: if we want to provide the standard movie editing behavior without using a movie controller, then we also need to keep track of the movie's current edit state w h e n e v e r we perform any editing operations. As w e ' v e seen, the application data record for QTMooVToolbox contains a field fMovieEditState, of type MovieEditState, which we'll use to hold the current edit state. Before we call any Movie Toolbox function that changes the contents of a movie, we can call the NewMovieEditState function to create a new movie edit state, as in this snippet from QTApp_HandleMenu" i f ((theMenultem-= IDM_EDITCUT) [[ (theMenultem == IDM_EDITPASTE) [[ (theMenultem == IDM EDITCLEAR)) ( i f ((**myAppData).fMovieEditState l= NULL) Di sposeMovieEdi tState ( ( **myAppData). fMovi eEdi tState) ; (**myAppData). fMovieEdi tState = NewMovieEditState(myMovie) ;
Notice that we need to dispose of any existing edit state (by calling Oi sposeMovi eEdi tState) before creating a new one. Otherwise, w e ' d be leaking memory. If the user selects the Undo m e n u item in the Edit menu, we need to reinstate the movie edit state that we have stored in our application data record. We do this by calling UseMovieEdi tState, like this: case IDM EDITUNDO: i f ((**myAppData).fMovieEditState == NULL) break; UseMovieEditState(myMovie, (**myAppData).fMovieEditState) ; Di sposeMovieEdi tState ( ( **myAppData). fMovi eEdi tState) ; (**myAppData). fMovieEdi tState = NULL; break;
Once we have used an edit state, we want to dispose of it and set the stored edit state reference to NULL so that we don't reinstate the same edit state. QTMooVToolbox supports only one level of undo, just like the standard linear movie controller. In theory, however, you can use NewMovieEditState and UseMovieEditState to support multiple levels of undo. Implementing this feature is left as an exercise for the reader.
68
Chapter3 Out of Control
There is one final complication to consider: if the user selects the entire movie and then cuts the current selection, the resulting movie is empty. It still exists, but it has no video or audio data in it. Since the movie has no video data, the movie box is empty. Now, if we had performed this cut using movie controller functions, the movie controller would have detected that the size of the movie had changed and would have notified our application by sending it the mcActionControllerSizeChanged movie controller action; in
response to this action we would have called our application's QTFrame_Si zeWindowToMovie function. But we didn't use movie controller functions t o p e r form the cut, so we need to handle this possibility ourselves. The simplest way to handle this situation is just to call QTFrame SizeWindowToMovie whenever we perform any editing operation that might have changed the size of the movie, like this" i f ((theMenultem == IDM_EDITUNDO) II (theMenultem == IDM_EDITCUT) II (theMenultem == IDM_EDITPASTE) II (theMenultem == IDM_EDITCLEAR)) { QTFrame_Si zeWindowToMovie (myWindowObject) ; (**myWi ndowObject), flsDi rty = true;
}
We now have all the pieces that we need to handle the Edit menu commands without using movie controllers. Listing 3.10 shows the QTApp_ HandleMenu function for QTMooVToolbox. (For readability, I've cut out the Test menu handling.)
Listing 3.10 Handling Edit menu items using the Movie Toolbox. Boolean QTApp_HandleMenu (UInt16 theMenultem) WindowObject AppI i cat i onDataHdl Movie Movie Boolean myWindowObject
=
myWindowObject = NULL; myAppData = NULL; myMovie = NULL; myEditMovie -- NULL; myI sHandl ed = false;
QTFrame GetWindowObjectFromFrontWi ndow()
;
i f (myWindowObject l= NULL) { myAppData = (Appl i cat i onDataHdl ) QTFrame_GetAppDataFromWi ndowObject (myWindowObject) ; myMovie = (**myWindowObject), fMovi e;
}
i f ((myWindowObject : : NULL)II (myAppData : : NULL)II (myMovie : : NULL)) return (mylsHandl ed) ;
Editing Movies
69
/ / before the Cut, Paste, and Clear commands, get the current edit state, / / after disposing of the currently saved edit state i f ((theMenultem == IDM_EDITCUT) JJ (theMenultem == IDM_EDITPASTE) JJ (theMenultem == IDM_EDITCLEAR)) { i f ((**myAppData).fMovieEditState != NULL) Di sposeMovi eEdi tState ((**myAppData). fMovi eEdi tState) ; (**myAppData). fMovieEdi tState = NewMovieEditState(myMovie) ;
}
switch (theMenultem) { / / Edit menu items; / / here we are overriding the framework's Edit menu handling / / (which uses movie controllers) case IDM EDITUNDO: / / restore the movie using the currently saved edit state, then dispose of i t i f ((**myAppData).fMovieEditState == NULL) break; UseMovieEditState(myMovie, (**myAppData).fMovieEditState) ; Di sposeMovi eEdi tState ((**myAppData). fMovi eEdi tState) ; (**myAppData) .fMovieEditState = NULL; break; case IDM EDITCUT. myEdi tMovi e = CutMovieSel ect i on (myMovie) ; break; D
case IDM EDITCOPY: myEditMovie = CopyMovieSelection(myMovie) ; break; case IDM EDITPASTE: myEdi tMovi e = NewMovieFromScrap(newMovieAct i ve) ; i f (myEditMovie ! = NULL) { PasteMovieSelection(myMovie, myEditMovie) ; Di sposeMovi e (myEditMovi e) ; myEdi tMovie = NULL;
}
break; case IDM EDITCLEAR: Cl earMovi eSel ecti on (myMovie) ; break;
70
Chapter3 Out of Control
case IDM EDITSELECTALL: SetMovieSelection(myMovie, OL, GetMovieDuration(myMovie)) ; break; / / Test menu items omitted here default: break; } / / switch (theMenultem) / / place any cut or copied movie segment onto the scrap i f (myEditMovie l= NULL) { PutMovieOnScrap(myEditMovie, OL) ; Di sposeMovie (myEditMovi e) ;
}
/ / after any commands that might have changed the movie, sync up the movie window size / / and mark the window as dirty i f ((theMenuItem == IDM_EDITUNDO) II (theMenultem == IDM_EDITCUT) II (theMenultem == IDM_EDITPASTE) I I (theMenultem == IDM_EDITCLEAR)) { QTFrame_Si zeWindowToMovie (myWindowObject) ; (**myWindowObject).flsDirty = true;
}
/ / for any Edit menu command, indicate that we handled i t i f (MENU_ID(theMenultem) == kEditMenuResID) myIsHandled = true; return (mylsHandl ed) ;
All in all, handling the Edit m e n u items using Movie Toolbox functions is not too much more complicated than doing it using the movie controller functions. We need to manage the movie edit states ourselves, and we need to make sure to resize a changed movie. But otherwise, the code is quite reminiscent of the movie controller editing code.
Looping Movies In the previous chapter, you might recall, we saw h o w to read a m o v i e ' s looping state from some user data stored in the movie file. If a movie file contains a user data item of type 'LOOP', then the data in that item determines w h e t h e r the looping state is normal looping (data is O) or palindrome looping [data is 1). If there is no such user data item in the movie file, then
Looping Movies
71
we assume that the movie does not loop. To read a movie's looping state, we defined the function QTUti ] s GetMovieFi ]eLoopingInfo, w h i c h returns one of three constants defined in our header file QTUti ] i t i es. h: m
enum{ kNormal Looping kPal i ndromeLoopi ng kNoLooping
!;
= 0, = 1,
=2
To set a movie's looping state based on the looping state stored in the file, we called the MCDoAction function, passing the two movie controller actions mcActionSetLooping and mcActionSetLoopIsPalindrome with appropriate combinations of true and fa]se. Now we want to see how to accomplish the same thing without using these movie controller actions. To manipulate a movie's looping state without using movie controller functions, we need to w o r k with the movie's time base, w h i c h defines the time coordinate system of the movie. We can think of a movie's time base like a vector that defines the direction and velocity of time for a movie. A movie's time base also defines the current movie time. So it makes sense that time bases are associated with looping: normal looping involves simply resetting the current movie time to 0 once the movie time reaches the end, whereas palindrome looping involves reversing the direction of time while keeping the velocity the same. The Movie Toolbox creates a time base for us w h e n we load a movie. Thereafter, we can retrieve a movie's time base by calling the GetMovieTimeBase function. The movie's looping state is determined by some of the time base control flags, a 32-bit value, which we can get and set by calling the functions GetTimeBaseFlags and SetTimeBaseFlags. The header file Movies.h defines these two time base flags related to looping: enum{ loopTimeBase pa 1 i ndromeLoopTi meBase
};
=1, =2
These constants are interpreted as bit masks for the time base control flags. In other words, you should think of ]oopTimeBase as 1L << 0 and pa] indromeLoopTimeBase as 1L << 1. As you might have guessed, we can set a movie's looping state by getting the current time base control flags, setting the appropriate bits on or off, and t h e n setting the revised time base control flags. Here's how we would enable palindrome looping:
72
Chapter 3 Out of Control
TimeBase long
myTimeBase = GetMovieTimeBase(theMovie); myFlags = GetTimeBaseFlags (myTimeBase) ;
myFlags [= loopTimeBase; myFlags [= pal indromeLoopTimeBase; SetTimeBaseFlags(myTimeBase, myFlags) ;
For optimal playback performance, however, we should take one further step, which is to set the movie's playback hints to reflect the desired looping state. A movie's playback hints specify one or more optimizations that the Movie Toolbox should use during movie playback. Once again, the playback hints are defined using individual bits in a 32-bit long word. These two bits are defined for setting movie looping hints: enum { hintsLoop hintsPal i ndrome
};
=1<<1, =1<<9
The Movie Toolbox provides the SetMoviePlayHints function for setting a movie's playback hints, but there is no corresponding fietMovieVlayHints function to get the current playback hints. Instead, SetMovieVlayHints requires us to pass it a 32-bit mask that determines which of the bits in the 32-bit play hints long word are to be considered. For example, to set the palindrome looping play hint on, we could do this: SetMoviePlayHints(theMovie, hintsLoop, hintsLoop); SetMoviePlayHints(theMovie, hintsPal indrome, hintsPal indrome) ;
These two lines of code set both the looping and palindrome looping play hints to be active. (Remember that looping ~must be enabled in order for palindrome looping to be enabled.) And to set the movie play hints to disable any looping, we could execute this line: SetMoviePlayHints(theMovie, OL, hintsLoop [ hintsPalindrome);
So, putting this all together, we see that to set the looping state of a movie, we need to set the time base control flags appropriately; we also should set the movie's playback hints to optimize playback performance. Listing 3.11 defines our complete QTMT_SetMovieLoopState for setting a movie's looping state.
Looping Movies
731
Listing 3.11 Setting a movie's looping state. void QTMT_SetMovieLoopState (Movie theMovie, UInt8 theLoopState)
{
Ti meBase long
myTi meBase; myFlags = OL;
i f (theMovie == NULL) return; myTimeBase = GetMovieTimeBase(theMovie) ; myFl ags = GetTimeBaseFlags (myTimeBase) ; switch (theLoopState) { case kNormalLooping: SetMoviePlayHints(theMovie, hintsLoop, hintsLoop); SetMoviePlayHints(theMovie, OL, hintsPalindrome) ; myFlags I = loopTimeBase; myFlags &= ~pal indromeLoopTimeBase; break; case kPal i ndromeLoopi ng: SetMoviePlayHints(theMovie, hintsLoop, hintsLoop); SetMoviePlayHints(theMovie, hintsPal indrome, hintsPal indrome) ; myFlags I = loopTimeBase; myFlags I = palindromeLoopTimeBase; break; case kNoLooping: default: myFlags &= ~loopTimeBase; myFlags &= ~pal indromeLoopTimeBase; SetMoviePlayHints(theMovie, OL, hintsLoop I hintsPalindrome); break; SetTimeBaseFlags(myTimeBase, myFlags) ;
For certain purposes, we sometimes want to know w h e t h e r a movie is looping and w h e t h e r it is palindrome looping. Based on what we've learned so far, we can easily define the function OTMT_IsMovieLooping shown in Listing 3.12, which returns a Boolean value that indicates w h e t h e r looping {either normal or palindrome} is enabled for the specified movie.
14
Chapter 3 Out of Control
Listing 3.12 Determining whether a movie is looping. Boolean QTMT_IsMovieLooping (Movie theMovie)
{
Ti meBase long
myTi meBase; myFl ags = OL;
i f (theMovie == NULL) return(false); myTimeBase = GetMovieTimeBase(theMovie) ; myFl ags = GetTimeBaseFlags (myTimeBase) ; return((Boolean) (myFlags & loopTimeBase)) ;
And we can easily define the function QTMT_IsMoviePalindromeLooping, shown in Listing 3.13, to tell us whether palindrome looping is enabled for the specified movie.
Listing 3.13 Determining whether a movie is palindrome looping. Boolean QTMT_IsMoviePalindromeLooping (Movie theMovie)
{
Ti meBase l ong
myTi meBase; myFl ags = OL;
i f (theMovie == NULL) return(false); myTimeBase = GetMovieTimeBase(theMovie) ; myFl ags = GetTimeBaseFlags (myTimeBase) ; return((Boolean) ((myFlags & loopTimeBase) && (myFlags & palindromeLoopTimeBase)));
Our application QTMooVToolbox uses these functions to set the appropriate check marks on the Loop and the Loop Back And Forth menu items in the Test menu, like this: QTFrame_SetMenultemCheck(myMenu, IDM_SET_LOOPING, QTMT_IsMovieLooping(myMovie) && !QTMT_IsMoviePalindromeLooping(myMovie)) ; QTFrame_SetMenuItemCheck(myMenu, IDM_SET_PALINDROME_LOOPING, QTMT_IsMovi ePaI i ndromeLoopi ng (myMovi e) ) ;
Looping Movies
75
Playing Picture-in-PJdure Movies Last Christmas, I was hoping that Santa Claus would bring me a new television set, perhaps a bit larger than the one I have now, and possibly also w i t h the so-called picture-in-picture capability, where you can tune into a second channel that's displayed in a smaller box in the corner of the main picture. Well, Santa wasn't that generous this year, so I decided to see w h e t h e r QuickTime could help satisfy my craving to watch two video sources at once (see Figure 3.4 once again). It turns out that it's surprisingly straightforward to use the Movie Toolbox to embed one movie inside of another movie. Let's call the movie that we are embedding the picture-in-picture movie and the movie we're embedding it into the main movie. In the broadest outlines, we want to open the movie file that contains the picture-in-picture movie, set that movie's graphics port to be the w i n d o w that already contains the main movie, and then set the picture-in-picture movie's enclosing rectangle to fit within the main movie window. Then we need to ensure that the main movie doesn't draw on top of the picture-inpicture movie; we do this by setting the main movie's display clipping region to exclude the rectangle occupied by the picture-in-picture movie. Finally, we need to task both movies in order to update the movie images and play the movies' sound. Let's see how to do these things.
Setting the Picture-in-Picture Movie Geometry Since we want to draw the picture-in-picture movie in the same w i n d o w as the main m o v i e - - a n d indeed on top of the main m o v i e - - w e need to set the graphics port of the picture-in-picture movie to the same graphics port used by the main movie. We can do that quite easily, like this: GetMovieGWorld(myMainMovie, &myGWorld, NULL); SetMovieGWorld(myPIPMovie, myGWorld, NULL) ;
But we don't want to draw the picture-in-picture movie at its natural size. Instead, we want it to occupy some smaller portion of the main movie. For simplicity, we'll set the picture-in-picture movie to have a height and w i d t h that are one-third those of the main movie. GetMovieBox(myMainMovie, &myRect) ; myValue : (myRect.bottom - myRect.top) / 3; myRect.top +: myValue; myRect.bottom -= myValue;
76
Chapter3 Out of Control
myValue = (myRect.right - myRect.left) / 3; myRect.left += myValue; myRect.right -= myValue; SetMovieBox(myPIPMovie, &myRect) ;
Note that this strategy will result in the picture-in-picture movie being distorted, unless its original dimensions are proportional to the dimensions of the main movie. It would be easy, however, to modify this code to retain the original proportions of the picture-in-picture movie while limiting its largest dimension to one-third the height or width of the main movie. [This refinement is left as an exercise for the reader.I Finally, let's keep track of the picture-in-picture movie and its new rectangle in the application data structure attached to the main movie window. (**myAppData). fPIPRect = myRect; (**myAppData).fPIPMovie = myPIPMovie;
Setting the Main Movie's Display Clipping Region If we simply started playing the picture-in-picture movie and the main movie using the geometry we've set up so far, we would get an annoying flickering caused by the main movie image being drawn over the existing picture-in-picture movie image, which in turn is then refreshed over the main movie image. To avoid this, we want to set up the main movie so that it doesn't draw within the rectangle that encloses the picture-in-picture movie. We can do this by defining a new display clipping region for the main movie. A movie's display clipping region is the portion of the movie box in which the movie image is to be drawn. That is to say, the display clipping region defines a clipping region that is applied to a movie just before it is displayed. [A movie also has a clipping region, but that region is applied much earlier in the imaging pipeline and isn't relevant to us here.I By default, a movie's display clipping region exactly coincides with its movie box, but it's possible to set any subregion of the movie box as the display clipping region. In the current situation, we want the main movie's display clipping region to be the rectangle occupied by the main movie minus the rectangle occupied by the picture-in-picture movie. To calculate this clipping region, we can use standard QuickDraw functions to get the regions corresponding to the two movie boxes and then subtract one region from the other. We set this region as the main movie's display clipping region using the SetMovieDisplayCl ipRgn function. This is all accomplished in the function QTMT SetMovieClipRegion defined in Listing 3.14. The Movie Toolbox copies the display clipping region that we pass it,
Playing Picture-in-Picture Movies
77
so we can safely dispose of that region, as well as the two intermediate regions we use to calculate the display clipping region, before exiting QTMT_SetMovieEl i pRegi on.
Listing 3.14 Setting the display clipping region of the main movie. OSErr QTMT_SetMovieClipRegion (WindowObject theWindowObject) Rect RgnHandle RgnHandle RgnHandle Appl icationDataHdl
myRect; myMovieRegi on; myPIPRegion; myCl ipRegion; myAppData= NULL;
/ / get the application-specific data myAppData = (Appl i cat i onDataHdl ) QTFrame_GetAppDataFromWi ndowObject (theWi ndowObject) ; i f (myAppData == NULL) return (paramErr) ; myMovieRegion = NewRgn(); myPI PRegion = NewRgn() ; myCl i pRegion = NewRgn() ; GetMovieBox((**theWindowObject). fMovie, &myRect); RectRgn(myMovieRegion, &myRect) ; myRect = (**myAppData). fPIPRect; i f ( I EmptyRect(&myRect)) MaclnsetRect(&myRect, -kPIPBorderSize, -kPIPBorderSize) ; RectRgn (myPIPRegion, &myRect); Di ffRgn(myMovieRegion, myPIPRegion, myClipRegion) ; SetMovi eDi spl ayCl ipRgn( (**theWi ndowObject), fMovi e, myClipRegion) ; Di sposeRgn(myMovieRegion) ; Di sposeRgn(myPI PRegion) ; Di sposeRgn(myCl i pRegion) ; return (noErr) ;
Notice that we call MaclnsetRect inside of QTMT_SetMovieClipRegion to expand the picture-in-picture movie box by a preset amount (kPIPBorderSi ze) before converting that box to a region. We do this to provide a few pixels of space in which to draw a border around the picture-in-picture movie, which
78
Chapter3 Out of Control
gives it a somewhat better appearance. {Listing 3.15 provides the code that draws the border.) There is one final thing worth mentioning: if the main movie were being played using a movie controller component, then we should set the movie display clipping region using the function MCSetClip instead of SetMovieDi spl ayCl ipRgn.
Playing the Picture-in-Picture Movie Now that w e ' v e o p e n e d the picture-in-picture movie and p o s i t i o n e d it w i t h i n the main movie window, we need to start the picture-in-picture movie playing and keep it playing. All the lessons we learned earlier in this chapter apply here as well, so we'll kick things off by preprerolling the picture-in-picture movie, like this: PrePrerolIMovie(myPIPMovie, O, GetMoviePreferredRate(myPIPMovie), gMoviePPRolICompleteProc, (void *)theWindowObject) ;
We're using the same movie preprerolling completion function that we used for the main movie, which prerolls the movie as soon as the preprerolling is completed. But you'll recall from Listing 3.7 that the completion procedure includes a few extra lines that apply only to the picture-in-picture movie: i f (theMovie == (**myAppData).fPIPMovie) { QTMT_SetMovieLoopState(theMovie, kNormalLooping) ; StartMovi e(theMovi e) ;
}
Since we're not going to provide a way for the user to start or stop the picture-in-picture movie, we call QTMT_SetMovieLoopState {defined in Listing 3.11) to set the movie looping state to normal looping. The movie will then keep playing, over and over, until we close the window or replace it with some other picture-in-picture movie. Then, we call StartMovie to start the picture-in-picture movie playing. So the only thing that remains for us to do is task the movie periodically to keep it playing back smoothly. As before, this is something we want to do in our idle routine {QTApp_Idle), where we are already calling MoviesTask on the main movie. We have several options here. First, we could just add these few lines of code to QTApp_Idle, to explicitly task the picture-in-picture movie" i f ((**myAppData).fPIPMovie i= NULL) MoviesTask((**myAppData). fPIPMovie, DoTheRightThing) ;
Playing Picture-in-Picture Movies
79
Or, we could pass the value NULLas the first parameter to MoviesTask, like this: MoviesTask(NULL, DoTheRightThing) ;
When we specify NULL in place of a movie, we're instructing the Movie Toolbox to service all open movies belonging to the application. Remember, however, that we want to draw a border around the picture-in-picture movie. So the option we'll actually choose will be to call an application-defined function" i f ((**myAppData) .fPIPMovie ! = NULL) QTMT_DrawPicture I nPi ctureMovi e (myWindowObject) ; QTMT_DrawPicturelnPictureMovie simply calls MoviesTask on the picture-in-
picture movie and draws a nice-looking border around the movie, as shown in Listing 3.15.
Listing 3.15 Drawing the picture-in-picture movie and its border. OSErr QTMT_DrawPicturelnPictureMovie (WindowObject theWindowObject) { Appl icationDataHdl
myAppData = NULL;
i f (theWindowObject == NULL) return (paramErr) ; myAppData = (Appl i cat i onDataHdl ) QTFrame_GetAppDataFromWi ndowObject (theWi ndowObject) ; i f (myAppData == NULL) return (paramErr) ; / / draw the current frame of the picture-in-picture movie i f ((**myAppData).fPIPMovie [= NULL) MoviesTask((**myAppData). fPIPMovie, DoTheRightThing) ; i f (!EmptyRect(&(**myAppData).fPIPRect)) PenSta te myPenStat e; Rect myRect; myRect = (**myAppData).fPIPRect; / / draw a pseudo-grayscale border Get PenState (&myPenState) ;
80
Chapter 3 Out of Control
{
MacI nsetRect (& (**myAppData). fP I PRect, - kPI PBorderSi ze, -kP I PBorderSi ze) ; RGBForeColor (&gBl ack) ; MacFrameRect (& (**myAppData). fPI PRect) ; MaclnsetRect(&(**myAppData).fPIPRect, 1, 1); RGBForeColor (&gWhi te) ; MacFrameRect (& (**myAppData). fP I PRect) ; MaclnsetRect(&(**myAppData).fPIPRect, 1, 1); RGBForeColor (&gLGray) ; MacFrameRect (& (**myAppData). fP I PRect) ; (**myAppData). fPIPRect = myRect;
}
Set PenState (&myPenState) ;
return (noErr) ;
Moving the Picture-in-Picture Movie Let's finish up by adding a simple e n h a n c e m e n t to our picture-in-picture movie playback capability: w h e n e v e r the user clicks the mouse button and the cursor is inside of the main movie window, let's move the picture-inpicture movie so that its upper-left corner is at the location of the click. Our basic cross-platform QuickTime framework passes mouse button clicks to the application function QTApp_HandleContentCl i ck w h e n e v e r those clicks fall within the w i n d o w ' s content area. So all we need to do is add some code to QTApp_Handl eContentCl i ck.
Moving the picture-in-picture movie rectangle is very simple. First, we need to convert the point that's passed to us in the event record into local coordinates: myPoi nt = theEvent->where; Global ToLocal (&myPoint) ;
T h e n we n e e d to calculate the n e w movie box for the p i c t u r e - i n - p i c t u r e movie. The size of the movie box isn't changing, only its upper-left corner. So we can call MacOffsetRect to figure out w h e r e to place the movie box and SetMovieBox to actually move it. MacOffset Rect (& (**myAppData). fP I PRect, myPoint.h - (**myAppData).fPIPRect.left, myPoint.v - (**myAppData). fPIPRect, top) ; SetMovieBox((**myAppData). fPIPMovie, &(**myAppData). fPIPRect) ;
Playing Picture-in-Picture Movies
81
Finally, we need to recalculate the display clipping region of the main movie, like this" QTMT_SetMovieCl i pRegi on (myWindowObject) ;
The complete procedure for moving the picture-in-picture movie in response to mouse clicks is shown in Listing 3.16. Listing 3.16 Moving the picture-in-picture movie. void QTApp_HandleContentClick (WindowReference theWindow, EventRecord *theEvent)
{
GrafPt r WindowObject Appl icationDataHdl
mySavedPort; myWindowObject = NULL; myAppData = NULL;
Get Port (&mySavedPort) ; MacSetPort (QTFrame GetPortFromWindowReference (theWi ndow)) ; m
myWindowObject = QTFrame_GetWindowObjectFromWi ndow(theWi ndow) ; myAppData = (Appl icationDataHdl)QTFrame_GetAppDataFromWindow(theWindow) ; i f ((myWindowObject == NULL) II (myAppData == NULL)) return; / / move the picture-in-picture movie to the specified location i f ((**myAppData).fPIPMovie l= NULL) { Point myPoint; myPoi nt = theEvent->where; Global ToLocal (&myPoint) ; / / i f the main movie i s n ' t playing, erase the rectangle currently occupied / / by the picture-in-picture movie i f (!QTMT_IsMoviePlaying((**myWindowObject).fMovie)) { Rect myRect; myRect = (**myAppData).fPIPRect; MaclnsetRect (&myRect, -kPIPBorderSize, -kPIPBorderSi ze) ; EraseRect (&myRect) ;
82
Chapter3 Out of Control
MacOffset Rect (& (**myAppData). fP I PRect, myPoint.h - (**myAppData).fPIPRect.left, myPoint.v - (**myAppData). fPIPRect.top) ; SetMovieBox((**myAppData). fPIPMovie, &(**myAppData). fPIPRect) ; QTMT_SetMovieCl i pRegi on (myWindowObject) ; MacSetPort (mySavedPort) ;
Conclusion Keep in mind that the point of this chapter is not that we should be playing movies using the Movie Toolbox alone, without the assistance of movie controllers. Indeed, as we've seen, movie controllers do lots and lots of useful work for us, as well as a good deal of h u m d r u m housekeeping (such as setting the movie rate to 0 w h e n the movie reaches the end). Still, there are occasions w h e n we might need to manage a movie without using a movie controller, and we've seen (fairly exhaustively, I hope) w h a t we need to do to accomplish that. But our larger goal here was to get acquainted with the Movie Toolbox itself, to get a taste of its capabilities and to see how to operate on movies directly.
Conclusion
83
This Page Intentionally Left Blank
The Image
introduction QuickTime is perhaps best known for its ability to play audio and video, but over the years it has gained the ability to handle quite a large number of other types of media, including text, MIDI data, virtual reality, sprite animation, vector-defined images, and streamed audio and video. QuickTime also provides a very powerful set of capabilities for managing still images {or graphics) stored in any of a large number of common image file formats. For instance, we can use QuickTime's application programming interfaces to open and display PICT, TIFF, JPEG, BMP, PhotoShop, GIF, PNG, and FlashPix files [to name only a handful of the supported formats). Moreover, we can use QuickTime to save an image in any one of a number of image formats, including PICT, TIFF, JPEG, BMP, PhotoShop, and PNG. These two aspects of handling images--reading them from files and writing them to files--are handled by parts of QuickTime known as graphics importers and graphics exporters. In this chapter, we'll investigate the most fundamental ways of using graphics importers and exporters to manipulate still images. The most obvious benefit that graphics importers and exporters provide is to insulate our applications from the nitty-gritty details of any particular image file format and image compression scheme. We can use exactly the same routines to open and display a JPEG file as we use to open and display a PICT file. In fact, our application never really needs to know what kind of image file it has opened. We can always determine this information about the image file if we want to, but for most uses that's information we simply don't need. Graphics importers and exporters provide a host of other services. We can change the image matrix used by a graphics importer when drawing an image, thereby drawing the image at a different size or orientation. We can also change the graphics mode used by a graphics importer; this allows us, for instance, to composite the image on top of other images or on top of QuickTime movies. 85
In this chapter, we'll see how to open an image file, read the image from it, and draw that image in a window on the screen. We'll also see how to alter the image matrix to draw the image at different sizes and orientations. Finally, we'll see how to export the image into some other type of image format. To wrap this all up into a neat package, let's set ourselves the goal of replicating as much of the functionality of QuickTime's PictureViewer application as possible. Figure 4.1 shows PictureViewer's Image menu, and Figure 4.2 shows the Image menu of our application, which I'll call QTGraphics. As you can see, these menus are quite similar. The main difference is that QTGraphics adds a check mark in the menu to indicate the current size of the image window. This is a useful feature and it's relatively simple to add, given the way we've chosen to handle our images. Another difference is that QTGraphics does not support the Fill Screen menu command. The reason for this is simply that fitting an image to the current screen size is extremely platform-specific and not terribly enlightening, at least in terms of using graphics importers. So I've left the implementation of that feature as an exercise for the reader. Finally, the Image menu of QTGraphics contains the
86
Figure 4.1
The Image menu from the PictureViewer application.
Figure 4.2
The Image menu from the QTGraphics application.
Chapter 4 The Image
Export item, which PictureViewer places in its File menu (where it more properly belongs). Along the way, we'll take a few small detours to explore some other features of graphics importers and exporters. We'll consider briefly how to handle image files that contain more than one image, and we'll take a quick look at how to distinguish image files from other kinds of files. So let's get started.
Importing Images A graphics import component, or graphics importer, is a software component that provides services for handling still images. Graphics importers were introduced in QuickTime version 2.5 to facilitate opening and drawing images. Subsequent versions of QuickTime have added new graphics importers and expanded the capabilities of existing importers. For instance, QuickTime 4 added the ability to work with files that contain multiple images or multiple image layers (such as FlashPix files or PhotoShop files). It's very simple to open an image file and display the image(s) contained in the file using the application programming interfaces provided by graphics importers. Suppose that we've got a file system specification (that is, an FSSpec) that picks out an image file. Then we can use the QTGraph_ShowImageFromFile function defined in Listing 4.1 to display that image in a window on the screen. Listing 4.1 Opening an image file and displaying its image. void QTGraph_ShowImageFromFile (FSSpec *theFSSpec)
{
GraphicslmportComponent Rect WindowPtr
myImporter = NULL; myRect; myWindow = NULL;
GetGraphicslmporterForFile(theFSSpec, &mylmporter) ; i f (mylmporter ! = NULL) { Graphi cs ImportGetNatura I Bounds(myImporter, &myRect) ; MacOffsetRect(&myRect, 50, 50); myWindow = NewCWindow(NULL, &myRect, NULL, true, noGrowDocProc, (WindowPtr)-lL, true, O) ; i f (myWindow ! = NULL) { GraphicslmportSetGWorld(mylmporter, (CGrafPtr)myWindow, NULL); Graphics ImportDraw (mylmporter) ; Cl oseComponent(mylmporter) ;
}
}
Importing Images
87
QTGraph_ShowlmageFromFi I e first calls the GetGraphics ImporterForFi I e function, which opens the specified image file and determines which graphics import component (if any) can handle the image data contained in that file. If GetGraphicsImporterForFile finds a suitable graphics importer, it returns an instance of that importer in the myImporter parameter. We'll use that graphics importer instance, of type GraphicsImportComponent, in all our subsequent calls to graphics importer functions. The type GraphicsImportComponent is simply a component instance: typedef ComponentInstance
Graphics ImportComponent;
As a result, we shall eventually need to close the component instance by calling CloseComponent {as shown in the final line of Listing 4.1). GetGraphicslmporterForFile uses a fairly straightforward algorithm for deciding what kind of image a file contains. First, on Macintosh systems, it looks at the file's type. For instance, if the specified file is of type 'PI CT', then GetGraphicsImporterForFile opens an instance of the PICT image importer. Otherwise, if it cannot find a suitable importer based on the file's type, GetGraphicsImporterForFile inspects the filename extension, if it has one. So, for example, a file whose name ends with .gi f would be imported as a GIF image. Finally, if neither of these steps reveals the type of the image in the file, then GetGraphicsImporterForFi l e sequentially opens an instance of each available graphics importer and instructs it to examine some of the data in the file to see whether it can handle that kind of data. (Image files often contain a header that helps identify the type of image data contained in them.) This process continues until some importer reports that it can handle the image data or until the list of available importers is exhausted. As you can imagine, this final step (called validating the image data) might take a fair amount of time to complete. If we are fairly certain that either the file type or filename extension will tell us what kind of image file we've got (perhaps because they are files we had previously created), then we can use the function GetGraphics ImporterForFi I eWithFl ags, specifying the kDontUseVal i dateToFindGraphi cslmporter flag to suppress the validation step. For a single file, seeing whether GetGraphicslmporterForFile returns a non-NULL importer--even allowing it to perform the validation step--is a perfectly reasonable way of determining whether that file contains an image (as shown in Listing 4.2). But for a large number of files, using GetGraphicsImporterForFile in this way would be too slow. Later on, we'll see a faster way of finding the image files among a large number of files.
88
Chapter4 The Image
Listing 4.2 Determining whether a file contains an image. Boolean QTUtils IslmageFile (FSSpec *theFSSpec)
{
m
Graphics ImportComponent
myImporter = NULL;
GetGraphicslmporterForFile(theFSSpec, &mylmporter) ; i f (myImporter ! = NULL) Cl oseComponent(mylmporter) ; return(mylmporter ! = NULL);
Let's return to Listing 4.1. If GetGraphicslmporterForFile returns a graphics importer instance to us, then we want to use it to draw the image in a window on the screen. We first call GraphicsImportGetNaturalBounds to determine the natural size of the image, which we shall use to set the size of the image window. GraphicsImportGetNaturalBounds always returns a rectangle whose top-left corner is at the origin--that is, at the point (0, 0). We then offset the rectangle a little bit down and to the right, so that (on Macintosh computers) the window's title bar is not obscured by the menu bar. Then we call NewCWindow to create a window in which we can draw the image. Before we can draw the image into that window, we need to set the graphics port of the graphics importer instance, by calling GraphicsImportSetGWorld (in the same way that, in past chapters, we needed to call SetMovieGWorld to set the graphics port of a movie). Finally, we can draw the image into the window by calling GraphicsImportDraw. Figure 4.3 shows the result of calling QTGraph_ShowImageFromFi l e for the sample image installed in the QuickTime folder. As you might imagine, QTGraph_ShowImageFromFile runs equally well under Windows. Figure 4.4 shows the result of executing it on a Windows computer. So far then, using barely a handful of graphics importer functions, we've opened an image file and drawn it at its natural size in a window on the screen. This is impressive. But of course the QTGraph_ShowImageFromFile function doesn't represent a complete solution for opening and displaying image files. For one thing, the title bar of the image window doesn't have a name, which violates good user interface practice. More importantly, the image won't be redrawn if the image window is wholly or partially obscured by some other window and then uncovered. If we want to replicate the functionality of the PictureViewer application, we need to do a bit more work to make things work just right.
Importing Images
89
Figure 4.3 An image file opened using the QTGraph_ShowlmageFromFile function (Macintosh).
Figure 4.4 An image file opened using the QTGraph_ShowlmageFromFil e function (Windows).
90
Chapter 4 The Image
We could, of course, start from scratch and develop a new image-handling application, but that might be a lot of work. Instead, let's see how easy it would be to modify the QTShell application to handle image files as well as movie files. I think we'll be pleasantly surprised.
Expanding the Application Framework Believe it or not, the basic QTShell application can already open and display image files, without directly using any graphics importer functions. Try it: launch QTShell and select the Open menu item in the File menu; then select an image file that you've got lying around and, voilA, the image opens in a window. How can this be? And more to the point" if the basic application we've developed so far can already open image files, w h y bother with graphics importers? Let's consider first how it is that QTShell can open and display image files. When the user selects the Open item in the File menu, our function QTFrame_0penMovieInWindow calls the function StandardGetFilePreview to display to the user a list of files that our application can open. The types of files displayed in that list are determined by the type list passed to StandardGetFilePreview. QTShell passes just one file type, kQTFileTypeMovie, like this: OSType short StandardFi I eReply
myTypeList = kQTFileTypeMovie; myNumTypes = 1; myRepI y;
StandardGetFi lePreview(NULL, myNumTypes, (ConstSFTypeListPtr)&myTypeList, &myReply) ;
The kQTFileTypeMovie constant tells StandardGetFilePreview to list any kinds of files that QuickTirne can open as a movie. On the Macintosh, this includes all files whose file type is 'MooV', and on Windows it includes all files whose file extension is .mov. On both platforms, this constant also causes StandardGetFi lePreview to list any files that can be translated into the QuickTime movie format using a movie importer, which is a software component that can convert certain kinds of files into movies. For example, QuickTime includes a movie importer that can convert AIFF audio files into
Expanding the Application Framework
91
sound-only QuickTime movies. So AIFF files will be shown in the list of files displayed by StandardGetFilePreview w h e n we include kQTFileTypeMovie in the file t ~ e list. At this point, if the user selects one of the files in the list displayed by StandardGetFi I ePrevi ew, QTShell calls the OpenMovieFi I e and NewMovieFromFile functions to get the movie contained in the selected file. If NewMovieFromFi l e determines that the selected file is not a QuickTime movie file, then it looks for a movie importer that can handle the data in the file. For an image file, NewMovieFromFil e invokes a movie importer that opens the image file (using, you guessed it, a graphics importer) and converts it into a movie. The resulting movie has a default duration of 1/15th of a second. The net result of all this importing and converting is that what began life as a still image is now being treated by QTShell as a movie. In particular, our application framework happily attaches a movie controller bar to the converted image, as shown in Figure 4.5. This provides an easy way to resize the image, to be sure, but it's probably not the behavior w e ' d like our applications to exhibit. After all, the user probably thought that he or she was opening an image file, not a movie file. So we want to expand our basic application framework so that it can handle still images without importing them as movies. That is to say, we want to be able to open and manage still images using the graphics importer routines
Figure 4.5
92
An image file opened by a movie importer.
Chapter 4 The Image
discussed earlier. This involves sprinkling a grand total of just over 20 lines of code here and there in our existing framework files. The first thing we need to do is add a field to the w i n d o w object record associated with each w i n d o w that our application opens. The w i n d o w object record now looks like this: typedef struct { WindowReference fWi ndow; Movie fMovie; Movi eControl ler fControl ler; Graphi cs ImportComponent fGraphi cs Importer; FSSpec fFi I eFSSpec; short fFi leResID; short fFi I eRefNum; Boolean fCanResi zeWindow; Boolean flsDirty; Boolean f l sQTVRMovie; QTVRInstance flnstance; OSType fObj ectType; Handle fAppData; } WindowObjectRecord, *WindowObjectPtr, **WindowObject;
The field fGraphicslmporter holds the graphics importer instance, if any, that is being used to manage the still image in the specified window. If we do things right, then either fGraphicsImporter or fMovie will be non-NULL, but not both. This allows us to tell, by inspecting the w i n d o w object record, whether a w i n d o w contains a still image or a movie. The next thing we need to do is prevent our application from calling OpenMovieFile and NewMovieFromFile on any graphics files we open. We can accomplish this by attempting to open a file as a still image before attempting to open it as a movie. So we'll add these lines to the QTFrame_OpenMovieInWindow function: myErr = GetGraphicsImporterForFile(&myFSSpec, &mylmporter) ; i f (mylmporter ! = NULL) goto gotlmageFi le;
Then we'll save the value r e t u r n e d by GetGraphicslmporterForFile in the new field in the w i n d o w object record, like this" (**myWi ndowObject), fGraphi cs Importer - mylmporter;
The last change we need to make to the QTFrame_OpenMovielnWindow routine is to set the graphics world for the graphics importer"
Expanding the Application Framework
93
myPort = (CGrafPtr)QTFrame_GetPortFromWindowReference(myWindow) ; i f (mylmporter ! = NULL) GraphicslmportSetGWorld(mylmporter, myPort, GetGWorldDevice(myPort)) ;
Elsewhere in our application's source code, we need to make a couple of changes whenever we determine the size of a window. There are two occasions w h e n this happens. First, in the Macintosh code that handles w i n d o w dragging, we need to pass the rectangle enclosing the dragged w i n d o w to the OragAlignedWindow function. Previously, w h e n our w i n d o w s always contained movies, we could call GetMovieBox to get this rectangle. Now, we'll have to call either GetMovieBox or GraphicsImportGetBoundsRect, depending on w h e t h e r the w i n d o w being dragged contains a movie or a still image: i f ((**myWindowObject).fMovie l= NULL) GetMovieBox( (**myWindowObject). fMovie, &myRect); i f ((**myWindowObject).fGraphicsImporter ! = NULL) Graphi cs ImportGetNatural Bounds( (**myWindowObject). fGraphi cs Importer, &myRect) ;
Similarly, w h e n we set the size of a w i n d o w (in our function QTFrame SizeWindowToMovie), we need to distinguish between graphics windows and movie windows. Here we'll call GraphicsImportGetNaturaIBounds if the w i n d o w belongs to a still image and not to a movie: i f (mylmporter l= NULL) { Graphi cs ImportGetNatural Bounds(myImporter, &myMovieBounds) ; goto gotBounds;
}
Notice that our application framework does not attach a grow box or scroll bars to an image w i n d o w and so does not allow the user to resize the image window. The function QTFrame_Si zeWi ndowToMovie (which now, alas, is misnamed) is called for an image w i n d o w only once, w h e n the image is first opened. That's w h y we call firaphi cs ImportfietNatural Bounds to set the image size there. Next, we need to make sure that an image w i n d o w gets redrawn correctly if any part of it gets covered up and then uncovered. Whenever this happens, an update event is issued for the affected w i n d o w (on the Macintosh), or a WM_PAINTmessage is sent to the affected w i n d o w ' s w i n d o w procedure (on Windows). In both cases, we can simply call GraphicslmportDraw to redraw the image, like this:
94
Chapter4 The Image
if
(myWindowObject ! = NULL) i f ((**myWindowObject).fGraphicslmporter ! = NULL) Graphi cs ImportDraw ( ( **myWi ndowObject ). fGraph i cs Importer) ;
The final thing we need to do is remember to close the graphics importer when the window containing the still image is being closed; so we'll add these lines to the function QTFrame CloseWindow0bject: m
i f ((**theWindowObject).fGraphicsImporter ! = NULL) { Cl oseComponent ( (**theWi ndowObject ). fGraphi cs Importer) ; (**theWindowObject).fGraphicsImporter = NULL;
}
That completes the changes we need to make to our basic application framework in order to support still images in addition to movies. (Now wasn't that pleasantly easy?)
Transforming Images Now that we've modified our application framework to handle both image and movie files, we can proceed with our main concern in this chapter, which is to replicate most of the capabilities of the PictureViewer application. Recall that we want to support the selection of items in the Image menu shown in Figure 4.2. Listing 4.3 shows how we'll handle those selections" we'll just call some application-defined function in response to any of the selected menu items.
Listing 4.3 Handlingthe items in the Image menu. Boolean QTApp_HandleMenu (UInt16 theMenultem)
{
WindowObject Boolean
myWindowObject= NULL; mylsHandled = false
myWindowObject = QTFrame_GetWindowObjectFromFrontWi ndow() ; switch (theMenultem) { case IDM HALF SIZE" case IDM NORMAL SIZE" case IDM DOUBLE SLZE: case IDM FILL SCREEN" QTGraph_Scal elmage(myWi ndowObject, theMenuItem) ; mylsHandled = true; break; m
m
Transforming Images
95
case IDM ROTATE LEFT: case IDM ROTATE RIGHT: QTGraph_Rotatelmage(myWindowObject, theMenultem) ; mylsHandled = true; break; case IDM FLIP HORIZcase IDM FLIP VERTQTGraph_Fl i plmage(myWindowObject, theMenultem) ; mylsHandled = true; break; case IDM EXPORT IMAGE: QTGraph_Export Image(myWindowObject) ; mylsHandled = true; break; default. break;
return (mylsHandl ed) ;
So our work will be done once we define the four QTGraph_ functions called in QTApp_HandleMenu. With the exception of QTGraph_ExportImage, which we'll consider later, all these functions operate primarily by manipulating the image matrix, which determines the orientation and size of the image drawn by the graphics importer. So let's take a minute to get acquainted with image matrices.
Working with Image Matrices An image matrix (or image transformation matrix) is a 3-by-3 array of numbers that specifies how to map an image from one two-dimensional coordinate space into another two-dimensional coordinate space. QuickTime defines the Matri xRecord data type for working with matrices: struct MatrixRecord ( Fixed
};
96
Chapter4 The Image
matrix[3] [3];
Pay attention to the fact that the elements of a MatrixRecord structure are of type Fi xed, which represents a fixed-point n u m b e r (that is, a n u m b e r consisting of an integer part and a fractional part, w h e r e there are a fixed number of bytes allotted to each part of the number). In a Fixed data type, the two high-order bytes are the integer part of the fixed-point n u m b e r and the two low-order bytes are the fractional part of the fixed-point number. So, for example, the n u m b e r 1.5 would be represented as 0x00018000, and 2.25 would be represented as 0x00024000. The header file FixMath.h contains a n u m b e r of useful functions for converting between long and fixed-point data types. We'll use the Long2Fix and FixRatio functions to help us specify the appropriate fixed-point values in our image matrices. FixMath.h also defines the constant fixed1, which we'll use instead of calling Long2Fix(1). There are a n u m b e r of standard transformations that we can perform on an image, such as enlarging or shrinking it, rotating it about some point, moving it horizontally or vertically, and skewing it (that is, essentially, grabbing a corner of it and stretching it). Each of these types of transformations is associated with some modification to the 3-by-3 image matrix. For instance, to translate an image horizontally, we need to modify only the [2][0] component of the image matrix. Similarly, to change the width of an image, we need to modify only the [0][0] component of the image matrix. To save us from having to r e m e m b e r all this, QuickTime provides a n u m b e r of functions that we can use to set up a matrix to perform some desired transformation. For present purposes, we shall use the Scal eMatri x, RotateMatri x, TranslateMatrix, and SetldentityMatrix functions. (The identity matrix is the matrix that transforms an image into the identical image; in other words, the identity matrix leaves the image unchanged.) Let's consider a few concrete examples here. Suppose that we have an image whose top-left corner is located at the point (0, 0). Then we can double the width and height of that image by executing this line of code:
ScaleMatrix(&myMatrix, Long2Fix(2), Long2Fix(2), O, 0); The last two parameters specify the horizontal and vertical coordinates of the anchor point of the scaling {that is, the point that stays fixed during the scaling operation). For simplicity, we'll always anchor our scaling to the point (0, 0), which we'll maintain as the top-left corner of the image. Next, let's see how to flip an image horizontally. It turns out that we can do this simply by scaling the image by a factor of -1 in the horizontal direction. This effectively just flips the image across the y-axis"
ScaleMatrix(&myMatrix, Long2Fix(-1), fixed1, O, 0);
Transforming Images
97
Figure 4.6 Scalingand translating to flip an image horizontally.
But there is a complication here. If we flip the image across the y-axis in this manner, the top-left corner of the image is no longer located at (0, 0). Instead, it's located at (-n, 0), where n is equal to the width (in pixels) of the image. If we want the top-left corner of the image to remain at (0, 0), then we need to translate the image back to the right after we've flipped it horizontally:
ScaleMatrix(&myMatrix, Long2Fix(-1), fixed1, O, 0); TranslateMatrix(&myMatrix, Long2Fix(myRect.right), O) ; (Here we assume that myRect is the rectangle that encloses the image.) Note that the matrix functions ScaleMatrix and TranslateMatrix modify the matrix they are passed so that it incorporates the indicated transformation. In other words, ScaleMatrix adds (or in mathematical jargon, concatenates) the specified scaling to the existing transformations in myMatrix. So calling ScaleMatrix and then TranslateMatrix results in a matrix that scales and then translates the image. With matrices, the order of operations is important; doing a translation before a scaling almost always results in a different image than doing the scaling before the translation. Figure 4.6 shows the result of scaling and then translating an image to flip it horizontally.
Flipping Images Now we've got the important ammunition that we need to handle the Flip Horizontal and Flip Vertical m e n u items in the Image menu. In a nutshell, we need to get the current image matrix, concatenate a scale matrix and a translate matrix to that image matrix, and then set the revised matrix as the new image matrix. We can use the GraphicslmportGetMatrix function to get
98
Chapter 4 The Image
the current image matrix and the Graphi cslmportSetMatri x function to set the
image matrix. Recall, however, that we also need to know the rectangle enclosing the image, so that we can translate the flipped image horizontally or vertically to return its top-left corner to the origin. A graphics importer component provides the GraphicslmportGetBoundsRect function, which returns the current size of the image after the existing image matrix has been applied to it. The rectangle returned by GraphicsImportGetBoundsRect always has its l e f t and top fields set to O, so we can use the right and bottom fields to determine the width and height of the image. Listing 4.4 shows our QTGraph_FlipImage function.
Listing 4.4 Flipping an image horizontally or vertically. OSErr QTGraph_Fliplmage (WindowObject theWindowObject, UInt16 theFlipDirection)
{
Graphi cslmportComponent Matri xRecord Rect OSErr
mylmporter = NULL; myMatri x; myRect; myErr = paramErr;
i f (theWindowObject == NULL) goto bai I ; mylmporter = (**theWindowObject). fGraphicslmporter; i f (mylmporter == NULL) goto bai I ; myErr = GraphicslmportGetMatrix(mylmporter, &myMatrix) ; i f (myErr ! = noErr) goto bai I ; myErr = GraphicslmportGetBoundsRect(mylmporter, &myRect) ; i f (myErr ! = noErr) goto bai I ; switch (theFlipDirection) { case IDM FLIP HORIZ: ScaleMatrix(&myMatrix, Long2Fix(-1), fixedl, O, 0); TranslateMatrix(&myMatrix, Long2Fix(myRect.right), O) ; break; case IDM FLIP VERT: ScaleMatrix(&myMatrix, fixed1, Long2Fix(-1), O, 0); TranslateMatrix(&myMatrix, O, Long2Fix(myRect.bottom)) ; break;
Transforming Images
99
default: return (paramErr) ;
myErr = GraphicslmportSetMatrix(mylmporter, &myMatrix) ; i f (myErr ! = noErr) goto bai I ; myErr = GraphicslmportDraw(mylmporter) ; bail 9 return (myErr) ;
}
Notice that we call GraphicslmportDraw before exiting QTGraph_Fl i plmage so that the image in the w i n d o w gets r e d r a w n using its new matrix.
Rotating Images Let's move on to consider the Rotate Left and Rotate Right m e n u items in the Image menu. In general, we can handle them in pretty m u c h the same way that we handled the Flip c o m m a n d s in OTGraph_F] i pImage: get the current image matrix, construct a new matrix for the desired rotation, add a translation matrix to return the top-left corner of the rotated image to the origin, and then set the new image matrix (Figure 4.7). But there is one important difference here" the size of the image changes w h e n we rotate it 90 ~ clockwise or counterclockwise (unless of course the original image is square). So we'll need to resize the w i n d o w that contains the image before we redraw the image.
Figure 4.7
1lOll
Rotating and translating to rotate an image clockwise.
Chapter 4 The Image
This complication is actually fairly easy to handle. We simply need to call GraphicsImportGetBoundsRect a second time, after we've set the new image matrix. GraphicsImportGetBoundsRect will then return to us the rectangle that encloses the image, after the new matrix has been applied to the image. This gives us the new height and width for our image window, which we can resize by calling SizeWindow. As before, we'll finish up by calling GraphicsImportDraw to redraw the image in its new rotated orientation. Listing 4.5 shows our function QTGraph_RotateImage for rotating images.
Listing 4.5 Rotating an image. OSErr QTGraph Rotatelmage (WindowObject theWindowObject, UInt16 thelmageRotation)
{
GraphicslmportComponent MatrixRecord Rect OSErr
mylmporter = NULL; myMatrix; myRect; myErr = paramErr;
i f (theWindowObject == NULL) goto bai I ; mylmporter = (**theWindowObject).fGraphicslmporter; i f (mylmporter == NULL) goto bai I ; myErr = GraphicslmportGetMatrix(mylmporter, &myMatrix) ; i f (myErr ! = noErr) goto bai I ; myErr = GraphicslmportGetBoundsRect(mylmporter, &myRect) ; i f (myErr ! = noErr) goto bai I ; switch (thelmageRotation) { case IDM ROTATE LEFT: RotateMatrix(&myMatrix, Long2Fix(-90), O, 0); TranslateMatrix(&myMatrix, O, Long2Fix(myRect.right)) ; break; case IDM ROTATE RIGHT: RotateMatrix(&myMatrix, Long2Fix(90), O, 0); TranslateMatrix(&myMatrix, Long2Fix(myRect.bottom), 0); break; default: return (paramErr) ;
Transforming Images 10'11
myErr = GraphicslmportSetMatrix(mylmporter, &myMatrix) ; i f (myErr != noErr) goto bai I ; myErr = GraphicslmportGetBoundsRect (mylmporter, &myRect) ; i f (myErr != noErr) goto bai I ; / / set the new window size Si zeWi ndow(QTFrame_GetWindowFromWindowReference ( (**t heWindowObject). fWi ndow), myRect.right, myRect.bottom, false) ; myErr = GraphicslmportDraw(mylmporter) ; bail 9 return (myErr) ;
}
Scaling Images The final image transformation we want to handle is scaling the image to a new size. As with rotating, scaling to a new size requires us to worry about setting a new w i n d o w size after we've updated the image matrix, but we can use the code we just developed to handle that. The added complication we face now is that the Half Size, Normal Size, and Double Size m e n u items specify absolute sizes, not relative sizes. That is to say, selecting the Half Size menu item should result in an image that is half its natural size, not half the current size of the image. So we can't just concatenate a scaling matrix onto the existing image matrix. There are several ways we could handle this complication. For my money, the most natural way is to keep track of the current size of the image and then perform the appropriate relative scaling w h e n we get a request to change its size. So we'll put the single field fCurrentSize into the application data structure associated with each window: typedef struct ApplicationDataRecord { UI nt 16 fCurrentS i ze; } Appl icationDataRecord, *Appl icationDataPtr, **Appl icationDataHdl ;
Then we can handle the Half Size m e n u c o m m a n d like this" case IDM HALF SIZE: i f ((**myAppData) .fCurrentSize == IDM_NORMAL_SIZE) ScaleMatrix(&myMatrix, FixRatio(1, 2), FixRatio(1, 2), O, 0);
102
Chapter4 The Image
i f ((**myAppData) .fCurrentSize == IDM_DOUBLE_SlZE) ScaleMatrix(&myMatrix, FixRatio(1, 4), FixRatio(1, 4), O, 0); break;
As you can see, we scale the image relatively by a factor of one-half or one-fourth, depending on whether the image currently is at its normal size or is twice its normal size. (Of course, if the image is already at half its normal size, we don't add any new scaling to the image matrix.) Listing 4.6 shows our complete function for handling image size changes.
Listing 4.6 Changing the size of an image. OSErr QTGraph_Scalelmage (WindowObject theWindowObject, UInt16 thelmageSize) Appl i cationDataHdl Graphi cs ImportComponent MatrixRecord Rect OSErr
myAppData = NULL; mylmporter = NULL; myMatrix; myRect; myErr = paramErr;
myAppData = (AppI i cat i onDataHdl ) QTFrame_GetAppDataFromWi ndowObject (theWi ndowObject) ; i f (myAppData == NULL) goto bai I ; mylmporter = (**theWindowObject). fGraphicsImporter; i f (mylmporter == NULL) goto bai I ; myErr = GraphicsImportGetMatrix(mylmporter, &myMatrix) ; i f (myErr ! = noErr) goto bai I ; switch (thelmageSize) { case IDM HALF SIZE" i f ((**myAppData) .fCurrentSize == IDM_NORMAL_SIZE) ScaleMatrix(&myMatrix, FixRatio(1, 2), FixRatio(1, 2), O, 0); i f ((**myAppData) .fCurrentSize == IDM_DOUBLE_SIZE) ScaleMatrix(&myMatrix, FixRatio(1, 4), FixRatio(1, 4), O, 0); break; case IDM NORMALSIZE" / / reset everything Set Identi tyMatri x (&myMatri x) ; break; n
Transforming Images 103
case IDM DOUBLESLZE: i f ((**myAppData).fCurrentSize == IDM HALF SLZE) ScaleMatrix(&myMatrix, Long2Fix(4), Long2Fix(4), O, 0); n
i f ((**myAppData).fCurrentSize == IDM_NORMAL_SIZE) ScaleMatrix(&myMatrix, Long2Fix(2), Long2Fix(2), O, 0); break; case IDM FILL SCREEN: / / l e f t as an exercise to the reader break; n
D
default: return (paramErr) ; (**myAppData).fCurrentSize = thelmageSize; myErr = GraphicslmportSetMatrix(mylmporter, &myMatrix) ; i f (myErr l= noErr) goto bai I ; myErr = GraphicslmportGetBoundsRect(mylmporter, &myRect) ; i f (myErr l= noErr) goto bai I ; Si zeWindow(QTFrame_GetWindowFromWindowReference ( (**t heWindowObject). fWi ndow), myRect.right, myRect.bottom, false) ; myErr = GraphicslmportDraw(mylmporter) ; bail: return (myErr) ;
}
Notice that the code for handling the Normal Size menu item is refreshingly simple" it just calls SetIdentityMatrix to reset the image matrix to the identity matrix. This has the effect of setting the image to its natural size and orientation, thereby undoing any scaling, rotation, and flipping the user may previously have performed. As mentioned earlier, one advantage of keeping track of the current size of the image is that we have an easy way to add a check mark to the correct item in the Image menu. Our function QTApp_AdjustMenus contains a few lines that look essentially like this:
104
Chapter 4 The Image
mySize = (**myAppData).fCurrentSize; for (myltem = IDM HALF SIZE; myltem <= IDM FILL SCREEN; myltem++) QTFrame_SetMenuI temCheck(myMenu, myl tem, mySize == myl tem) ;
Working with Multi-image Files Before moving on to consider graphics exporters, let's take a minute to see how we can work with files that contain more than one image. As I mentioned earlier, this capability was introduced in QuickTime 4. In particular, QuickTime 4 added the ability to import (but not export) graphics in the FlashPix format defined by the Digital Imaging Group. Also, QuickTime 4 added support for opening and displaying multiple images contained in PhotoShop files [which store layers as separate images in a single file). Earlier versions of QuickTime could open PhotoShop files but imported all the layers into a single image. You can determine how many images a particular graphics file contains by calling the GraphicslmportGetlmageCount function. And you can select which of those images is displayed by calling the GraphicslmportSetlmageIndex function. Listing 4.7 illustrates how to display all the images contained
in a specified file. The QTGraph_ShowImagesFromFi1e function is simply a modified version of QTGraph_ShowImageFromFile (defined in Listing 4.1) that loops through all the images in the image file, pausing a few seconds to display each image. Listing 4.7 Displaying all images in a graphics file. void QTGraph_ShowlmagesFromFile (FSSpec *theFSSpec)
{
GraphicslmportComponent Rect unsigned long WindowPtr
mylmporter = NULL; myRect; myCount, mylndex, mylgnore; myWindow = NULL;
GetGraphicslmporterForFile(theFSSpec, &mylmporter) ; i f (mylmporter i= NULL) { / / determine how many images are in the specified f i l e Graphi cs ImportGet ImageCount(myImporter, &myCount); / / loop through all images in the image f i l e , drawing each into a window for (mylndex = 1; mylndex <= myCount; mylndex++) { / / set the image index we want to display GraphicslmportSetlmagelndex(mylmporter, mylndex) ;
Working with Multi-image Files 105
Graphics ImportGetNatural Bounds(myImporter, &myRect); MacOffsetRect(&myRect, 50, 50); myWindow = NewCWindow(NULL, &myRect, NULL, true, noGrowDocProc, (WindowPtr)-lL, true, O) ; i f (myWindow ! = NULL) { GraphicslmportSetGWorld(mylmporter, (CGrafPtr)myWindow, NULL); Graphics ImportDraw(mylmporter) ; Delay(120, &mylgnore); / / wait 2 seconds Di sposeWi ndow(myWindow) ;
}
C1oseComponent(mylmporter) ;
Exporting Images A graphics export component, or graphics exporter, is a software component that provides services for saving a still image in a new format. While graphics importers allow us to read in images that are stored in any of a wide number of formats, graphics exporters allow us to write out images into any of a fairly large number of formats. Currently, the formats supported by QuickTime's graphics exporters are a subset of those supported by the graphics importers; but in theory there is nothing (other than programming resources and possibly also licensing restrictions) preventing the importers and exporters from supporting the same formats. Graphics exporters are relative newcomers to the QuickTime scene, having been introduced in their full glory only in version 4. But QuickTime has supported some means of exporting images from as early as version 2.5, which included the GraphicslmportSaveAsPicture and GraphicsImportSaveAsQuickTimeImageFile functions. QuickTime 3.0 added a handful of additional functions, including GraphicsImportExportImageFile and GraphicsImportDoExportImageFileDialog (which we'll investigate further shortly). These functions provided much needed services for converting images from one format to another, but they did not provide a very extensive set of capabilities for customizing the export process or the features of the exported images. The graphics exporters introduced in QuickTime 4 expanded the available export formats and greatly increased the ability of applications to manipulate images during export. Moreover, the newly defined interface for graphics exporters opened the door for third parties to create custom graphics exporters.
106
Chapter4 The Image
Here we'll take a look at two very basic ways of exporting image files. First we'll show how to use GraphicsImportDoExportImageFileDialog to present a standard export image dialog box to the user. Then we'll take a quick look at exporting images without involving the user, first using Graphi csImportExportImageFi ]e and then using the graphics exporter APIs.
Exporting Images Using the Export Image Dialog Box If we're running PictureViewer and have opened an image file, we can select the Export item in the File menu to save the image in a new format. When we select that item, we are presented with the export image dialog box shown in Figure 4.8. As you can see, this dialog box allows you to select an output filename and location, a file type, and some image format options. For instance, if we select the JPEG format for the exported file and click the Option button, we'll see the dialog box that's shown in Figure 4.9. It's actually quite easy to add this capability to our QTGraphics application. QuickTime provides the GraphicslmportDoExportlmageFileDialog function, which we can use to display the export image dialog box and handle all the low-level details of creating the output file and writing the appropriate image data to that file. Indeed, GraphicsImportDoExportImageFileDialog even takes the trouble to append the correct filename suffix to the output file name {although the user can change or remove that suffix, if desired).
Figure 4.8 The export image dialog box.
Exporting Images 107
Figure 4.9 An options dialog box. Graphics ImportDoExport ImageFi I eDi al og takes seven parameters. The first, of course, is the graphics importer that we are using to manage the image to be exported in a new format. The second parameter is a file system specification that indicates a suggested location and name for the output file. We'll have QTGraphics pass in the specification of the image that's open in the window (that is, the file being exported). Since presumably the user will select a new image format and GraphicsImportDoExportImageFileDialog will adjust the filename suffix automatically, we shouldn't run into any danger of overwriting the existing image file. The third parameter to Graphi csImportDoExportImageFi l eDi a log is a Pascal string that is displayed as a prompt in the export image dialog box. Like Pico tureViewer, we'll pass in the string "Save Image As:". The fourth parameter is a universal procedure pointer (UPP) to a modal dialog filter function, which can intercept events passed to the dialog box. In QTGraphics, we'll pass a UPP to the function QTGraph_ExportImageFileDial ogEventFilter, which in turn calls the filter function QTFrame StandardModalDialogEventFilter defined in the file MacFramework.c. The important work done by QTFrame_StandardModalDialogEventFilter is to look for update events that are targeted at one of our application's windows; if it finds any, it calls QTFrame_HandleEvent to dispatch the update event to the correct movie or image window. In practice, this means that any part of the movie or image window that is obscured by some other window and then uncovered will be redrawn, even if the export image dialog box is still displayed on the screen. It's interesting to note that PictureViewer does not seem to have a modal dialog filter function installed here, since it doesn't redraw its image windows while the export image dialog box is displayed. (On Windows, update messages are sent directly to the affected window, so we don't need to install a filter function here; if you look at the QTGraph_ExportImage-
108
Chapter 4 The Image
FileDialogEventFilter function, you'll see that on W i n d o w s it simply returns fa] se to indicate that it didn't handle the event.) The last three parameters to firaphicsImportDoExportImageFileDialog are used to communicate back to its caller some information about the newly created file. Since we don't care about that information, we'll just pass NULL in all three parameters. Listing 4.8 shows our function QTfiraph_ExportImage for exporting images.
Listing 4.8 Exporting an image into a user-selected format. OSErr QTGraph_ExportImage (WindowObject theWindowObject)
{
Graphics ImportComponent StringPtr Modal Fi I terYDUPP OSErr
mylmporter = NULL; myPrompt = QTUti I s ConvertCToPascal String(kExportlmagePrompt) ; myFi I terProcUPP = NULL; myErr = paramErr; m
i f (theWindowObject == NULL) goto bai I ; mylmporter = (**theWindowObject). fGraphicslmporter; i f (mylmporter == NULL) goto bai I ; myFi I terProcUPP = NewModalFi I terYDProc (QTGraph_Export ImageFi I eDi al ogEventFi I ter) ; myErr = Graphi cs ImportDoExport ImageFi I eDi al og ( mylmporter, &(**theWi ndowObject). fFi I eFSSpec, myPrompt myFi I terProcUPP, NULL, NULL, NULL) ; bail: Di sposeRout i neDescri ptor (myFi I terProcUPP) ; free (myPrompt) ; return (myErr) ;
Exporting Images Directly Sometimes we don't want to use the export image dialog box to help us export an image to a file. For instance, the user might want to convert a large
Exporting Images '1109
number of image files from one format to another, using the same settings for all the conversions. In this case, it would be tedious, at best, for the user to have to configure the desired settings in the export image dialog box for each image. Luckily, QuickTime supports more direct ways of exporting files. We can use the graphics exporter functions introduced in QuickTime 4, or {if we want our application to run in versions of QuickTime as early as 3.0) we can use the GraphicslmportExportlmageFile function. GraphicsImportExportImageFile is very easy to use and requires virtually no setup. We need to pass it the graphics importer instance attached to the image that we want to export, along with the desired output file format and a file system specification that indicates the output file. Here's how we might export an image to a JPEG file:
GraphicslmportExportlmageFile(mylmporter, kQTFileTypeJPEG, O, &myExportedFile, smSystemScript) ; The third parameter here specifies the output file's creator; by passing 0 in that parameter, we get the default creator for the specified file type. More often than not, the default creator is set to the PictureViewer application. The fourth parameter specifies the output file, which is created by GraphicsImportExport ImageFi le if it doesn't already exist. If the file does already exist, its data is replaced by the image being exported. When exporting the image data to the output file, GraphicsImportExportImageFi l e applies the current image matrix to the source image. This generally means that the exported image looks just like the image currently displayed on the screen. The only exception to this is when the top-left corner of the image is not located at (0, 0); in that case, GraphicsImportExportImageFi l e temporarily adjusts the image matrix so that the resulting image has a top-left corner that is located at (0, 0). To export an image directly using the graphics exporter programming interfaces, we first need to open an instance of a graphics exporter. That is to say, we need to open a component whose component type is GraphicsExporterComponentType and whose component subtype is the file type of the exported image file. For instance, to export an image as a JPEG file, we could call 0penADefaul tComponent like this:
OpenADefaultComponent(Graphi csExporterComponentType, kQTFiI eTypeJPEG, &myExporter) ; If OpenADefaultComponent finds a graphics export component that can handle JPEG files, it returns an instance of that exporter to us in the myExporter parameter. We'll use that instance in all of our subsequent calls to the graphics exporter.
110
Chapter4 The Image
Now that we've found a suitable graphics exporter, we need to do three things before we can call the GraphicsExportDoExport function to do the actual exporting. First, we need to tell the graphics exporter where to get the image data to export. Since our image is being handled by a graphics importer, we can call GraphicsExportSetlnputGraphicsImporter to tell the
exporter to use the importer as the source of the image data. Second, we need to tell the graphics exporter where to put the exported data. For the present, we'll give it a file, by calling firaphicsExportSetOutputFile. Finally, we might need to change some of the default export settings. For instance, the graphics exporter automatically gives an appropriate file type and creator to any files exported on Macintosh systems; if those settings are not appropriate, we could call GraphicsExportSetOutputFi l eTypeAndCreator to set some other tylae or creator. In the QTGraph_ExportlmageWithoutDialog function, defined in Listing 4.9, we'll explicitly set the output image quality to be codecNormal Qual i ty.
Listing 4.9 Exporting an image into a specified format. OSErr QTGraph_ExportlmageWithoutDialog (WindowObject theWindowObject, OSType theType) Graphics ImportComponent Graphi csExportComponent FSSpec StringPtr OSErr
mylmporter = NULL; myExporter = NULL; myExportedFi I e; myName = QTUtils ConvertCToPascaIString("temp") ; myErr = paramErr;
i f (theWindowObject == NULL) goto bai I ; myImporter = (**theWi ndowObject). fGraph i cs Importer; i f (mylmporter == NULL) goto bai I ; / / create an FSSpec for the f i l e containing the exported image myErr = FSMakeFSSpec(O, O, myName, &myExportedFile); i f ((myErr != noErr) && (myErr l= fnfErr)) goto bai I ; / / get a graphics exporter of the desired type myErr = OpenADefaultComponent(GraphicsExporterComponentType, theType, &myExporter) ; i f (myErr ! = noErr) goto bai I ; myErr = Graphi csExportSetlnputGraphi cslmporter(myExporter, mylmporter) ; i f (myErr ! = noErr) goto bai I ;
Exporting Images 111
myErr = GraphicsExportSetOutputFile(myExporter, &myExportedFile) ; i f (myErr I = noErr) goto bail ; myErr = Graphi csExportSetCompress i onQual i ty (myExporter, codecNormal Qual i ty) ; i f (myErr I= noErr) goto bail ; myErr = GraphicsExportDoExport(myExporter, NULL) ; bail: i f (myExporter ! = NULL) Cl oseComponent (myExporter) ; free (myName) ; return (myErr) ;
One thing worth noticing here is that (just like GraphicsImportExportImageFile) GraphicsExportDoExport will create the specified output file if it doesn't already exist. So we don't need to call FSpCreate to create the file picked out by myExportedFi l e.
Finding Image Files Before we close up shop, let's return to a topic we touched on earlier, namely, how to list to the user the files that our application is capable of opening. Recall that the QTShell application passes to StandardGetFilePreview the single file type kQTFileTypeMovie; this results in a list that includes all files that are of type 'MooV' or are of a type that can be imported by one of QuickTime's movie importers. As we saw, this list will also include all image files that QuickTime can open, since QuickTime includes a movie importer that can import image files. This is well and good for an application that wants to be able to open both movie files and image files. But it's less satisfactory for an application like PictureViewer that is concerned solely with image files. However, StandardGetFilePreview supports another constant, kQTFileTypeOuickTimelmage, which tells it to list all files that are of type 'qti f' or are of a type that can be imported by one of QuickTime's graphics importers. If I were a betting man, I'd wager a hefty sum that PictureViewer includes some source code that looks a lot like this:
112
Chapter4 The Image
OSType StandardFi I eReply
myTypeList = kQTFiI eTypeQuickTimeImage; myReply;
StandardGetFilePreview(NULL, 1, (ConstSFTypeListPtr)&myTypeList, &myReply);
For an application like QTShell or QTGraphics that knows how to handle both movies and images, we can specify that we want both movie files and image files listed in the file-opening dialog box, like this: OSType StandardFi I eReply
myTypeList [] = {kQTFileTypeMovie, kQTFi I eTypeQui ckTi meImage} ; myReply;
StandardGetFi lePreview((Fi leFi I terUPP)theFi I terProc, 2, (ConstSFTypeLi stPtr)myTypeLi st, &myReply) ;
As we've seen, adding kQTFileTypeQuickTimelmage here is overkill, but it's worth putting it in, if only to remind us that we're going to get image files as well as movie files. But now a problem presents itself. What if we want to make our application compatible with Carbon, the set of programming interfaces and libraries t h a t s u p p o r t execution on both Mac OS X and certain versions of the "classic" Macintosh operating system (namely, Mac OS 8 and Mac OS 9)? The Standard File Package is no longer available to Carbon applications, and its replacement, Navigation Services, does not provide any special processing for the constants kQTFi l eTypeMovie and kOTFi l eTypeOuickTimelmage. To make a long story short, what we need to do is provide a UPP to a l~le filter function when calling NavGetFi l e, the Navigation Services replacement for StandardGetFilePreview. This filter function is passed information about each file that is a candidate for being listed in the file-opening dialog box; the filter should return true for each file that our application wants to appear in that list of files. Suppose for the moment that we want our application to be able to open only image files. Should we just call the QTUtils_IslmageFile function defined in Listing 4.2 to determine whether a candidate file should be listed? The answer, as I've already hinted earlier, is no. In fact, that test would work just fine in separating the image files from the non-image files, but it would take far too long to do so. (Even on a relatively fast machine, using QTUtils_IslmageFile in our filter function to pick out image files would take several minutes.) A better strategy is first to build up a list of all the file types that we want our application to be able to open and then, in the file filter function called by NavGetFile, simply look to see whether a candidate file has a type that's in that list. This is the strategy adopted by QTShell and its descendants,
Finding Image Files 113
including QTGraphics. To build up this list of file types, we can iterate through all available graphics importers and ask them what kinds of file types they can handle. Listing 4.10 shows a part of a function QTFrame_AddComponentFileTypes that does this, using Component Manager functions to find all the available graphics import components.
Listing 4.10 Finding all image file types. ComponentDescri pt i on ComponentDescri pt i on Component
myFindCompDesc : {0, O, O, O, 0}; mylnfoCompDesc : {0, O, O, O, 0}; myComponent = NULL;
myFi ndCompDesc,componentType = Graphi cs ImporterComponentType; myFi ndCompDesc.componentFl ags = O; myFi ndCompDesc,componentFI agsMask = movie ImportSubType I s Fi I eExtens i on; myComponent = Fi ndNextComponent (myComponent, &myFindCompDesc) ; while (myComponent ! = NULL) { GetComponentlnfo(myComponent, &mylnfoCompDesc, NULL, NULL, NULL); gVal i dFi I eTypes [*theNext Index] = mylnfoCompDesc, componentSubType; *theNextlndex += 1; myComponent = Fi ndNextComponent (myComponent, &myFindCompDesc) ;
Notice that the componentFlags and componentFlagsMask fields of the component description that we're using to find graphics importers are set up to exclude any graphics importers whose subtype is a file extension. That's because we want to find only those importers whose subtype is a Macintosh file type. (One consequence of this, however, is that our file filter function will exclude files that don't have a recognized file type but do have a recognized filename extension. So our Navigation Services code doesn't quite offer the full functionality of the Standard File Package version.) Once we've built the list of image types that the available graphics importers can handle, we can use that list inside of our file filter function. We don't need to go into the details of that here; if you're interested, take a look at the function QTFrame_GetOneFileWithPreview in the source code file ComFramework. c.
Conclusion We've actually accomplished quite a lot in this chapter. We've seen how to make sure that image files appear in the list of files displayed by the fileopening dialog box (either using StandardGetFilePreview or NavGetFile).
114
Chapter 4 The Image
We've learned how to find a graphics importer capable of opening any of those files and how to use a graphics importer to draw an image in a window on the screen. We've also learned how to perform some simple transformations on an image, by altering the image matrix used by the graphics importer. Finally, we've investigated several methods of exporting images into new image formats. So we've successfully managed to upgrade our existing QTShell application into QTGraphics, our poor man's PictureViewer. Nevertheless, we've barely even begun to cover the many capabilities provided by graphics importers and exporters. If you take a glance into ImageCompression.h (a standard header file provided by QuickTime, where the graphics importer and exporter functions are declared), you'll encounter a large number of functions that we haven't mentioned at all. There are graphic importer functions that allow us to work with data references instead of files (so we could open and display images addressed using URLs). There are functions that allow us to get and set the image clipping region, the source and destination rectangles, and the image quality. With graphics exporters, the situation is even more daunting; of the six dozen graphics exporter functions declared in ImageCompression.h, we have discussed exactly four of them here. Of course, this is only good news, since it means that QuickTime provides us with a very wide array of image importing and exporting services. As our image-handling needs grow, it's likely that QuickTime already provides services we can use to manage those needs.
Conclusion 115
This Page Intentionally Left Blank
In and Out
Introduction In the previous chapter, we looked at graphics importers and exporters, which allow us to read still images from files, draw those images, and save the images in new image formats. In this chapter, w e ' r e going to take a look at movie importers and exporters, which allow us to convert various kinds of data to and from the QuickTime movie format. A movie importer reads data and converts it into a QuickTime movie, and a movie exporter writes QuickTime movie data into some other format. For example, we can use a movie importer to read an AVI file and convert it into the QuickTime movie format. At that point, we can display the movie in a w i n d o w and attach a movie controller to it, exactly as if the original data had been stored in the QuickTime file format. Conversely, we can use a movie exporter to save QuickTime movie data as an AVI file. Because movie importers and exporters allow us to change the format of movie data, they are also called movie
data exchange components. Originally, movie importers and exporters were mainly intended to read and write data stored in files that are not QuickTime files. We can, however, use movie data exchange components for additional purposes. In particular, we can use movie exporters to change the compression format or compression settings of a QuickTime file. We can also use movie exporters to add hint tracks to a movie so that the movie can be streamed over a network. In this case, the existing movie data isn't actually being converted to some other format; rather, new tracks are being added to the movie to enable the movie data to be efficiently broken up into packets that can be sent out over a network. In this chapter, we'll begin by considering how to export a movie into a new format. We'll see how to do this in two ways, first allowing the user to select any available export format and then restricting the export format to a particular format. Next, we'll investigate how to import nonmovie files as
117
movies. Finally, we'll learn how to use movie progress functions, which the Movie Toolbox calls w h e n an operation {such as importing or exporting a movie} promises to take a significant a m o u n t of time.
Exporting Movies To export a movie is to convert it into a new format or to change the movie data in some other way. QuickTime provides a n u m b e r of functions that we can use to export a movie. By far the easiest to use is the ConvertMovi eToFile function, whose declaration (in Movies .h) looks essentially like this: OSErr ConvertMovieToFile ( Movie Track FSSpec * OSType OSType Scri ptCode short * long ComponentInstance
theMovie, onlyTrack, outputFi le, fi I eType, creator, scri ptTag, resID, flags, userComp) ;
Most of these parameters have pretty obvious uses: theMovie, of course, is the movie we want to export, and outputFile points to a file system specification for the file we want the converted movie data to be put into. The fileType and creator parameters are the desired file type and file creator code of the destination file, and scriptTag is the script into which the movie should be converted. A few of these parameters are less obvious. The onlyTrack parameter specifies which track in the source movie is to be converted; we'll always specify NULL for this parameter to have ConvertMovieToFile convert all the tracks in the movie. The reslD parameter points to some storage that will receive the resource ID of the source movie; we w o n ' t need this information, so once again we'll always pass NULLfor this parameter. The userComp parameter specifies which movie export component should be used to perform the data conversion. If we want the movie to be exported into a specific format, we can open the appropriate movie export component and pass the component instance in this parameter. On the other hand, if we want to display a dialog box that allows the user to select the desired output format, then we can pass NULLin this parameter. In that case, we should also specify 0 in the fi l eType parameter (since of course we don't yet know w h a t the file type of the output file should be).
118
Chapter 5 In and Out
Finally, the flags parameter specifies a 32-bit value whose bits encode information governing how the movie conversion should proceed. Our first example of using ConvertMovieToFile will use this line of code to configure the flags parameter: myFlags = createMovieFileDeleteCurFile I showUserSettingsDialog I movieFileSpecVal id I movieToFileOnlyExport; The createMovieFileDeleteCurFile nag tells ConvertMovieToFile to delete any existing file specified by the outputFile parameter. The showUserSettingsDialog flag indicates that ConvertMovieToFile should display a movie export dialog box, shown in Figure 5.1. If the showUserSettingsDialog flag is set, then the movieFileSpecValid flag indicates that the name specified in the name field of the file system specification pointed to by the outputFi l e parameter should be the name initially displayed in the export dialog box. Also, if showOserSettingsBialog is set, then the movieToFileOnlyExport flag indicates that the user should be allowed to select only from among the output formats supported by any available movie export components. These available formats are listed in the pop-up menu shown in Figure 5.2. On the other hand, if showUserSettingsDialog is
Figure 5.1 The movie export dialog box.
Exporting Movies 119
P :i:~ i:~84 ~i:i:::84
Sire:am Moule to FLC Movie to Hinted Movie M o v i e to: I:mage Sequence Movie to Picture Movie to QulckTIme Movie Sound to-RIFF Sound to System 7 Sound Sound to Wave SoUnd t o jsLoW Figure 5.2 The pop-up menu listing the available export formats.
set but the movieToFileOnlyExport flag is clear, and if fileType is either MovieFi l eType or O, t h e n the pop-up m e n u also includes items that allow the user to save the movie as a movie file or as a self-contained movie file. Figure 5.2 shows the export formats built into Q u i c k T i m e 4.1. Of course, since movie exporters are components, additional exporters can be a d d e d by third parties. So the pop-up m e n u on your m a c h i n e might contain a few m o r e exporters than you see in Figure 5.2.
Converting to Any Available Export Format Listing 5.1 shows a function QTDX_ExportMovieAsAnyTypeFile that configures the movie export flags and then calls ConvertMovieToFi l e to allow the user to export a movie into any available export format. Listing 5.1
Exporting a movie as a user-selected type.
OSErr QTDX_ExportMovieAsAnyTypeFile (Movie theMovie, FSSpec *theFSSpec)
{
FSSpec l ong OSErr
myFSSpec = *theFSSpec; myFlags = OL; myErr = noErr;
myFlags : createMovieFileDeleteCurFile I showUserSettingsDialog I movieFi leSpecValid I movieToFi I eOnlyExport;
120
Chapter 5 In and Out
/ / export the movie into a f i l e myErr = ConvertMovieToFile( theMovie, // NULL, // &myFSSpec, // // OL, FOUR CHARCODE( 'TVOD'), // smSystemScri pt, // NULL, // myFlags, // NULL); // D
the movie to convert all tracks in the movie the output f i l e the output f i l e type the output f i l e creator the script no resource ID to be returned export flags no specific export component
return (myErr) ;
Because the showUserSettingsDialog flag is set, ConvertMovieToFile displays the movie export dialog box shown in Figure 5.1. W h e n the user selects an output file and export format, ConvertMovieToFi l e creates that file (first deleting it if it already exists) and performs the desired conversion. Note that w h e n ConvertMovieToFile completes, it returns information about the newly created file in the myFSSpec parameter. (This behavior appears to be undocumented.) In our sample application, the theFFSpec parameter passed to OTDX_ExportMovieAsAnyTypeFile points to the file system specification of the open movie file. So we make a local copy of that specification in myFSSpec to avoid overwriting the movie's file information.
Converting to a Specific Export Format I mentioned earlier that we can specify a particular movie export component w h e n calling ConvertMovieToFile if we want to export a movie into a specific format. Let's suppose that we want to allow the user to add a hint track to a movie, so that it can be efficiently streamed across a network. The first thing we need to do is find the movie hinter export component. We can use the Component Manager functions FindNextComponent and OpenComponent to find that component and open an instance of it, like this: ComponentDescri pt i on
myCompDesc;
myCompDesc.componentType = MovieExportType; myCompDesc.componentSubType = MovieFileType; myCompDesc.componentManufacturer = FOURCHARCODE('hint'); myCompDesc.componentFlags = O; myCompDesc.componentFlagsMask = O; myExporter = OpenComponent(FindNextComponent(NULL, &myCompDesc)); m
Exporting Movies 12,1
As you can see, we're asking for a movie export c o m p o n e n t that can create movie files with tracks of type 'hint'. We'll pass myExporter as the last parameter w h e n we call ConvertMovieToFi l e. Now, what flags should we pass to ConvertMovieToFil e? We certainly want to pass createMovieFileDeleteCurFile and movieFileSpecValid. And we certainly don't want to pass movieToFileOnlyExport, because we already know what kind of output file we want to create. But what about showUserSett ingsDi a log? Do we want to display the movie export dialog box shown in Figure 5.1? For some purposes we might, but for the m o m e n t let's suppose that we don't want the user to change the output filename or location (which he or she could do if we displayed the movie export dialog box). So we w o n ' t include showUserSettingsDialog in the flags we pass to ConvertMovieToFi le. Now we've got a slight problem. While we don't want the user to change the output filename or location, we might want the user to change the settings used by the movie hinter export component. If the movie export dialog box were displayed, the user could click the Options button to display the settings dialog box shown in Figure 5.3. Luckily, we can use the movie hinter export component directly and ask it to display its settings dialog box, by calling the MovieExportDoUserDialog function like this: MovieExportDoUserDialog(myExporter, theMovie, NULL, O, O, &myCancelled);
Figure 5.3 The movie hinter settings dialog box.
122
Chapter 5 In and Out
So at this point, we've found the appropriate movie hinter export component and displayed its settings dialog box to allow the user to select the desired hinter settings. We can finish up by calling ConvertMovieToFile, specifying the movie hinter export component: myErr = ConvertMovieToFi le(theMovie, NULL, &myHintedFi le, MovieFi leType, FOUR CHAR CODE('TVOD'), smSystemScript, NULL, myFlags, myExporter); m
Is this line of code completes successfully, the specified movie will have been exported into a hinted movie file.
Using Movie Export Settings Imagine now that we've got a large number of movie files to which we want to add hint tracks. Imagine further that we want to use some specific nondeo fault settings for the hinting. It would be tedious to have to open each movie file and configure its export settings in the dialog box displayed by MovieExportDoUserDialog. Instead, it would be better to configure those settings once, save them somewhere, and then instruct the movie hinter export component to use those saved settings. The processing required to make this happen is actually rather simple. Let's suppose that theFSSpecPtr is a pointer to a file system specification for a file that contains a saved copy of the desired exporter settings. Then we can use the function QTDX_GetExporterSettingsFromFi le defined in Listing 5.2 to read those settings and install them as the exporter's active settings. Listing 5.2. Reading exporter settings from a file. OSErr QTDX_GetExporterSetti ngsFromFi I e (Movi eExportComponent theExporter, FSSpecPtr theFSSpecPtr)
{
Handle ComponentResul t
myHandl e = NULL; myErr = fnfErr;
myHandl e = QTDX_ReadHandleFromFi I e(theFSSpecPtr) ; i f (myHandle == NULL) goto bai I ; myErr = MovieExportSetSetti ngsFromAtomContai ner (theExporter, (QTAtomContainer)myHandl e) ; bail 9 i f (myHandle ! = NULL) Di sposeHandl e (myHandle) ; return((OSErr)myErr) ;
Exporting Movies
123
The function QTDX_ReadHandleFromFile reads the data in the specified file into a handle; there is nothing especially interesting about it so we w o n ' t discuss it further. The important function here is MovieExportSetSettingsFromAtomContainer, which takes that handle of data, interprets it as an atom container, and uses the settings in that atom container as the current settings of the specified movie exporter. An atom container is a handle to a block of m e m o r y that is structured in a hierarchical arrangement of container atoms (which contain other atomsl and leaf atoms (which contain data). In a future chapter, we'll take a closer look at the structure of atom containers and see how to create and parse them. But for the moment, we can remain blissfully ignorant of those details, because we can use the function MovieExportGetSettingsAsAtomContainer to create the settings atom container. Listing 5.3 shows our function that saves the current settings of the specified movie exporter into a file.
Listing 5.3 Writing exporter settings into a file. OSErr QTDX_SaveExporterSettingslnFile (MovieExportComponent theExporter, FSSpecPtr theFSSpecPtr)
(
QTAtomContainer ComponentResult
myContainer = NULL; myErr = noErr;
myErr = MovieExportGetSettingsAsAtomContainer(theExporter, &myContainer) ; i f (myErr i= noErr) goto bai I ; myErr
=
QTDX WriteHandleToFile((Handle)myContainer, theFSSpecPtr) ;
bail 9 i f (myContainer ! = NULL) QTDisposeAtomContai ner (myContai ner); return((OSErr) myErr) ;
So what we need to do is display the movie hinter export c o m p o n e n t ' s settings dialog box once, allow the user to configure the hinter settings as desired, and then save those settings into a file by calling OTDX_SaveExporterSettingsInFile. Then, we can use those saved settings for any subsequent export operations. Listing 5.4 shows the complete function QTBX_ExportMovieAsHintedMovie that exports a movie as a hinted movie. Notice that this
124
Chapter 5 In and Out
function takes a Boolean parameter that indicates whether it should display the settings dialog box. Listing 5.4 Exporting a movie as a hinted movie. OSErr QTDX_ExportMovieAsHintedMovie (Movie theMovie, Boolean thePromptUser) ComponentDescri pt i on MovieExportComponent long FSSpec FSSpec Boolean Boolean Stri ngPtr St ri ngPt r ComponentResult
myCompDesc; myExporter = NULL; myFlags; myHi ntedFi I e; myPrefs Fi I e; mylsSelected = false; myIsReplacing = false; myPrompt; myFi I eName; myErr = badComponentType;
myFlags = createMovieFileDeleteCurFile I movieFileSpecVal id; myPrompt = QTUti I s ConvertCToPascal String(kHintedMovieSavePrompt) ; myFi leName = QTUti I s ConvertCToPascal String(kHintedMovieFi leName) ; / / get an output f i l e for the hinted movie QTFrame PutFile(myPrompt, myFileName, &myHintedFile, &mylsSelected, &mylsReplacing); i f (!mylsSelected) { myErr = userCanceledErr; goto bai I ;
}
i f (myIsReplacing) { myErr = FSpDelete(&myHintedFile) ; i f (myErr ! = noErr) goto bai I ;
}
/ / find and open a movie export component that can hint a movie f i l e myCompDesc.componentType = MovieExportType; myCompDesc,componentSubType = MovieFi I eType; myCompDesc.componentManufacturer = FOUR CHAR CODE('hi n t ' ) ; myCompDesc.componentFlags = O; myCompDesc.componentFlagsMask = O; myExporter = OpenComponent(Fi ndNextComponent(NULL, &myCompDesc)); i f (myExporter == NULL) goto bai I ;
Exporting Movies
125
/ / get the preferences f i l e for this application QTDX_GetPrefsFi leSpec(&myPrefsFi le, (void *)&myHintedFile) ; / / read existing movie exporter settings from a f i l e ; i f we aren't going to prompt / / the user for exporter settings, these stored settings will be used; otherwise, / / these stored settings will be used as i n i t i a l values in the settings dialog box QTDX_GetExporterSetti ngsFromFi I e (myExporter, &myPrefsFiI e) ; i f (thePromptUser && QTDX_ComponentHasUI(MovieExportType, myExporter)) { Bool ean myCancel Ied = false; / / display a dialog box to prompt the user for desired movie exporter settings myErr = MovieExportDoUserDialog(myExporter, theMovie, NULL, O, O, &myCancelled); i f (myCancelIed) goto bai I ; / / save the existing settings into our preferences f i l e QTDX_SaveExporterSettingslnFi le(myExporter, &myPrefsFile) ; / / export the movie into a f i l e myErr = ConvertMovieToFile( theMovie, NULL, &myHintedFi I e, MovieFi I eType, FOUR CHARCODE( 'TVOD'), smSystemScri pt, NULL, myFlags, myExporter) ;
// // // // // // // // //
bail/ / close the movie export component i f (myExporter ! = NULL) Cl oseComponent(myExporter) ; free (myPrompt) ; free (myFi I eName); return((OSErr)myErr) ;
126
Chapter5 In and Out
the movie to convert all tracks in the movie the output f i l e the output f i l e type the output f i l e creator the script no resource ID to be returned conversion flags hinter export component
I m p o r t i n g Files As we saw in the previous chapter, QuickTime occasionally imports files for us, without our having to explicitly find a movie importer or call any file conversion function. W h e n we call NewMovieFromFile and specify a file that isn't a QuickTime movie file, NewMovieFromFile looks for a movie importer that can handle the data in that file. If it finds one, it automatically uses that importer to convert the file data into the QuickTime movie format and returns the converted movie to us. So we can import files that are not QuickTime movie files simply by handing them to NewMovieFromFile and letting it work its magic. But there are a few details we need to take care of before we pass a file to NewMovieFromFile. First, if we want to mimic the behavior of QuickTime Player's Import m e n u item, then we need to make sure that the list of files displayed to the user in the file selection dialog box does not include QuickTime movie files. We also need to make sure that that list does include files of type 'TEXT' and 'PICT' (which by default are not listed in the file list displayed w h e n Open is chosen but which are displayed w h e n Import is chosen). Then, if we are not using the StandardGetFilePreview function to display that list of files, we need to determine w h e t h e r a file selected by the user needs to be converted into another file before it can be imported. Let's take these two tasks in order.
Filtering Out Movies The list of files displayed in response to selecting the Import m e n u item should not include any files that are QuickTime movies. If we are using the Navigation Services function NavfietFile, we can accomplish this by passing it a file filter function that accepts all files that QuickTime can open, except files of type kQTFileTypeMovie. Our application framework maintains a list of all files that QuickTime can open, either directly or using a movie importer or a graphics importer. So all our import file filter function needs to do is check to see w h e t h e r a candidate file has a type that's in that list but that isn't kQTFileTypeMovie. The function QTDX_FilterFiles defined in Listing 5.5 does just that.
Listing 5.5 Filtering out movies. PASCAL_RTN Boolean QTDX_FilterFiles (AEDesc *theltem, void *thelnfo, void *theCallBackUD, NavFi I terModes theFi I terMode)
{
#pragma unused(theCalIBackUD, theFilterMode) NavFileOrFolderlnfo *mylnfo = (NavFileOrFolderInfo *)theInfo;
Importing Files 1127
i f (gValidFileTypes == NULL) QTFrame_Bui I dFi I eTypeLi st () ; i f (theltem->descriptorType == typeFSS) { i f (!mylnfo->isFolder) ( OSType myType = mylnfo->fi leAndFolder, fi lelnfo, finderInfo, fdType; long myCount; long mylndex; / / see whether the f i l e type is in the l i s t of f i l e types that our application can / / open, but do not allow movie f i l e s myCount = GetPtrSize((Ptr)gValidFileTypes) / (long)sizeof(OSType) ; for (mylndex = O; mylndex < myCount; mylndex++) i f ((myType == gValidFileTypes[mylndex]) && (myType l= kQTFileTypeMovie)) return(true) ; / / i f we got to here, i t ' s a f i l e we cannot open return(false);
/ / i f we got to here, i t ' s a folder or non-HFS object return(true) ;
If we are running on Windows, where we are using the Standard File Package, it's even simpler. We can just pass StandardGetFilePreview a list of file types that includes all types that QuickTime can open, minus kQTFi l eTypeMovie. When we constructed the list of file types gVal idFi 1eTypes, we put kQTFileTypeMovie in the first position. So we can just pass a pointer that begins at the second file type, like this: myTypeLi stPtr = (QTFrameTypeListPtr)&gVal idFi leTypes [ i ] ; myNumTypes - (short) (GetPtrSize((Ptr)gVal idFileTypes) / sizeof(OSType)) - 1;
You might be wondering w h y we didn't also use a custom file filter function with StandardGetFilePreview. On the Macintosh, this would work fine; but on Windows, only the list of file types is used to determine which files to show in the file-opening dialog box.
128
Chapter5 In and Out
Importing In Place QuickTime can import some types of files without first having to make a copy of the file data. These kinds of files can be imported in place--meaning that the associated movie importer can construct a movie that directly references that data. Other kinds of files cannot be imported in place. For instance, w h e n we select QuickTime Player's Import m e n u item and choose a file of type 'PICT', we are presented with the dialog box shown in Figure 5.4, which asks us to specify a new file to hold the converted picture data. W h e n we specify a new file, the selected 'PICT' file is converted into that file and then the converted file is opened in a movie window. If we are using StandardGetFi lePreview to present a list of openable files to the user, we don't need to know w h e t h e r a file can be imported in place. StandardGetFi l ePreview determines this by itself and presents the file conversion dialog box whenever the selected file cannot be imported in place. But if we are using the Navigation Services programming interfaces, we do need to figure this out. Listing 5.6 defines a function that determines whether a given file can be imported in place. As you can see, we first find a movie importer that can open files whose type is that of the specified file (on the Macintosh) or whose file extension is that of the specified file (on Windows). Then we call GetComponentInfo to get a set of flags that specify the capabilities of that importer. For present purposes, we need to see w h e t h e r the bit canMovieImportInPlace is set.
Figure 5.4 The file conversion dialog box.
Importing Files 1 2 9
Listing 5.6 Determining whether a file can be imported in place. Boolean QTDX_FileCanBelmportedlnPlace (FSSpec *theFSSpec) ComponentDescription Component Boolean OSType unsigned long OSErr #if TARGETOS MAC FInfo m
myCompDesc; myComponent = NULL; myCanlmportlnPlace = false; mySubType; myFlags = O; myErr = noErr;
- _
myFileInfo;
/ / get the f i l e type of the specified f i l e myErr = FSpGetFInfo(theFSSpec, &myFilelnfo) ; i f (myErr l= noErr) goto bai I ; mySubType = myFilelnfo, fdType; #endi f #if TARGETOS WIN32 / / get the filename extension of the specified f i l e myErr = QTGetFileNameExtension(theFSSpec->name, OL, &mySubType); i f (myErr I= noErr) goto bai I ; m
m
myFl ags = movielmportSubTypelsFi leExtension; #endif myCompDesc.componentType = MovielmportType; myCompDesc,componentSubType = mySubType; myCompDesc.componentManufacturer = O; myCompDesc,componentFl ags = myFlags; myCompDesc,componentFl agsMask = myFlags; myComponent = FindNextComponent(NULL, &myCompDesc); i f (myComponent I= NULL) { GetComponentlnfo(myComponent, &myCompDesc, NULL, NULL, NULL); i f (myCompDesc.componentFlags & canMovielmportlnPlace) myCanlmportlnPlace = true;
}
bail: return (myCanlmportInPl ace) ;
}
130
Chapter 5 In and Out
importing Files N o w we have all the pieces we n e e d to handle the I m p o r t m e n u item. First we do the necessary w o r k to limit the files displayed in the file-opening dialog box to any files that Q u i c k T i m e can import but that are not Q u i c k T i m e movie files. T h e n we check to see w h e t h e r the file selected by the user can be i m p o r t e d in place. If it cannot, we n e e d to display a file-saving dialog box to elicit a new file from the user; we also need to convert the selected file into a movie file, w h i c h we can do using the ConvertFileToMovieFile function. Finally, we pass the converted file (or the originally selected file, if it can be imported in place) to our function QTFrame_OpenMovieInWindow, w h i c h in turn calls NewMovieFromFi l e. Listing 5.7 puts this all together.
Listing 5.7 Importing a file. OSErr QTDX_ImportAnyNonMovie (void)
{
QTFrameFileFilterUPP QTFrameTypeLi stPtr short Movie FSSpec FSSpec StringPtr OSErr
myFileFilterUPP = NULL; myTypeListPtr = NULL; myNumTypes = O; myMovie = NULL; myFi I eToConvert; myConvertedFi I e; myPrompt = QTUti I s ConvertCToPascal Stri ng (k ImportSavePrompt) ; myErr = noErr; D
# i f TARGET OS WIN32 myTypeLi stPtr = (QTFrameTypeListPtr)&gVal i dFi I eTypes [I] ; myNumTypes = (short) (GetPtrSize((Ptr)gValidFileTypes) / sizeof(OSType)) - I; #endif / / let the user select an openable f i l e from any f i l e s that aren't movie f i l e s myFi I eFi I terUPP = QTFrame_GetFi I eFi I terUPP ( ( ProcPt r) QTDX_Fi I terF i I es ) ; myErr = QTFrame_GetOneFiI eWi thPrevi ew(myNumTypes, myTypeListPtr, &myFiI eToConvert, (void *)myFi leFi IterUPP) ; i f (myErr l= noErr) goto bai I ; myConvertedFi le = myFileToConvert; / / determine whether the selected f i l e needs to be converted into another f i l e before / / QuickTime can open i t ; i f so, do the conversion # i f TARGET OS MAC i f (!QTDX_FileCanBelmportedlnPl ace(&myFi leToConvert)) { m
Importing Files 131
Boolean Boolean
mylsSelected = false; mylsReplacing = false;
/ / display the p u t - f i l e dialog to save the converted f i l e QTFrame_PutFile(myPrompt, myFileToConvert.name, &myConvertedFile, &myIsSelected, &mylsRepl acing) ; i f (!mylsSel ected) goto bai I ; / / delete any existing f i l e of that name i f (myIsReplacing) { myErr = DeleteMovieFi le(&myConvertedFi le) ; i f (myErr I= noErr) goto bai I ;
}
/ / import the f i l e into a movie myErr = ConvertFileToMovieFile( &myFi I eToConvert, &myConvertedFi I e, FOUR CHAR CODE('TVOD'), smSystemScri pt, NULL, OL, NULL, gMovi eProgressProcUPP, OL); m
}
m
// // // //
the the the the
f i l e to convert f i l e to convert i t into output f i l e creator script
#endif / / now open the (possibly) converted f i l e in a window i f (myErr == noErr) QTFrame_OpenMovielnWi ndow(NULL, &myConvertedFiI e) ; bail 9 i f (myFileFilterUPP ! = NULL) Di sposeRouti neDescri ptor (myFi I eFi I terUPP) ; free (myPrompt) ; return (myErr) ;
It's important to understand that our Macintosh implementation of the Import menu item lacks a key feature provided automatically by Standard-
132
Chapter5 In and Out
6etFilePreview. To wit: the file-saving dialog box displayed by the call to QTFrame_PutFi]e in Listing 5.7 does not contain an Options button that allows the user to modify any settings supported by the movie importer capable of opening the selected file. [Look again at Figure 5.4 to see the Options button provided by StandardGetFilePreview.) To add a custom button to the standard Navigation Services file-saving dialog box would take us too far afield right now. Let's put this item on our list of features to add at some time in the future.
Default Progress Functions Unless a movie is very short, the calculations and disk accesses involved in {for instance) exporting it to a new format can take several minutes, if not considerably longer, even on today's relatively fast machines. From its very inception, QuickTime has provided a way to inform the user that a lengthy operation is in progress and to provide some indication of how much of the operation has completed. These tasks are accomplished using a movie progress function, which typically displays a movie progress dialog box. In this section and the following two sections, we'll see how to display and manage a movie progress dialog box. By far the easiest way to display a progress dialog box is to use QuickTime's default progress function, which displays and manages a dialog box like the one shown in Figure 5.5 (on Macintosh computers) or in Figure 5.6 (on Windows computers). As you can see, these dialog boxes contain a progress bar control that shows the relative amount of completion of the operation, a text string indicating the operation that's in progress, and a button to
Figure 5.5 The default progress dialog box (Macintosh).
Figure 5.6 The default progress dialog box (Windows).
Default Progress Functions 133
cancel the operation. There are a dozen or so operations that can trigger the display of a movie progress dialog box, including exporting and importing movies, cutting or pasting movie segments, loading a movie into memory, and saving a movie as a self-contained movie. We can instruct QuickTime to display this default progress dialog box during lengthy operations on a particular movie by calling the SetMovieProgressProc function and p a s s i n g - 1 as the progress function universal procedure pointer. Our basic application framework includes this line of code to set the default function for each movie we open:
SetMovieProgressProc(myMovie,
(MovieProgressUPP)-l, O) ;
We need to take the word "default" here with a grain of salt, however. We'll get this default progress dialog box only if we call SetMovi eProgressProc with -1 as the second parameter. If we open a movie, fail to call SetMovieProgressProc, and then initiate a lengthy operation, QuickTime does not display any progress dialog box at all. This might lead the user to think that our application has frozen, so it's almost always a good idea to use a progress function that provides some visual feedback.
Custom Progress Functions The default progress function in fact does a fair amount of work for us. It displays the default progress dialog box, continually updates the progress bar control in the dialog box, and responds to user clicks on the Stop button. In addition, it looks for user presses on the Escape key and Command-Period key combination and interprets those presses as equivalent to a click on the Stop button. Finally, it displays a message indicating which operation is in progress. Not bad for a single line of code. Still, it's tempting to want to jazz things up a bit, and QuickTime provides a way for us to install a custom progress function that is called periodically during a lengthy operation. We're free to do just about anything in our custom progress function. We can display a different dialog box or message, replace the progress bar control by some other progress indicator, play sounds, and the like. For the moment, we'll restrain our urges to bloat our progress dialog box with features. Instead, we'll retain the basic appearance and operation of the default progress dialog box, while adding two features: we'll add a text message that indicates the approximate amount of time remaining in the operation, and we'll add a picture that is gradually erased (from bottom to top) as the operation progresses. Figure 5.7 shows our custom progress dialog box in action. As you've already seen, we install a custom progress function by passing its universal procedure pointer to the SetMovieProgressProc. So, if our cus-
134
Chapter 5 In and Out
Figure 5.7 The custom progress dialog box of QTDataEx. tom progress function is QTDX_MovieProgressProc, we can install it by executing these lines of code" gMovieProgressProcUPP = NewMovieProgressProc (QTDX_MovieProgressProc) ; i f ((**theWindowObject).fMovie ! = NULL) SetMovi eProgressProc ( (**theWi ndowObject). fMovi e, gMovieProgressProcUPP, (long) theWi ndowObject) ;
The third p a r a m e t e r to SetMovieProgressProc is an arbitrary 32-bit reference constant that's passed to the movie progress function each time it's called. Here we are passing the w i n d o w object associated with the movie. We don't actually use that value in our custom progress function, but it's not hard to imagine things we could do with that information. Our custom movie progress function has this declaration: PASCAL_RTN OSErr QTDX_MovieProgressProc (Movie theMovie, short theMessage, short theOperation, Fixed thePercentDone, long theRefcon);
As you can see, this f u n c t i o n has five p a r a m e t e r s , two of w h i c h are the movie being o p e r a t e d u p o n and the r e f e r e n c e c o n s t a n t that we specified w h e n we called SetMovieProgressProc. The theMessage p a r a m e t e r is a value that indicates w h y our progress function is being called. The Movie Toolbox defines these constants for this parameter: enum { movi eProgressOpen movi eProgressUpdatePercent movi eProgressCl ose
};
=0, =
1~
=2
Custom Progress Functions 135
So our custom progress function gets called w h e n the lengthy operation is started, w h e n it has stopped, and at various percentages of completion. The progress function is called often enough for us to keep our dialog box updated in a fairly smooth manner. If theMessage is movieProgressUpdatePercent, then the thePercentDone parameter indicates the percentage of completion. This percentage is always specified as a Fixed value between 0.0 and 1.0. The parameter the0peration is a constant that specifies which operation has triggered the custom progress function. The Movie Toolbox defines these 12 constants: enum { progressOpFl atten prog res sOpInsert Trac kSegment progressOplnsertMovi eSegment progressOpPaste progressOpAddMovieSel ecti on progressOpCopy progressOpCut prog res sOpLoadMovi eI ntoRam prog res sOpLoadTrack I ntoRam progres sOpLoadMedi aI ntoRam progres sOpImportMovi e progressOpExportMovi e
};
=1, =2, = 3~ = 4,
= 5~ = 6~ = 7~ = 8p = 9t = 10, = 11, = 12
We'll use this information to determine which string to display at the top of our custom progress dialog box, like this" GetDialogltem(myDialog, kProgressTextltemID, &myltemKind, &myltemHandle, &myI temRect) ; i f ((theOperation > O) && (theOperation <= progressOpExportMovie)) { GetlndString(myString, kOperationsStringsResID, theOperation); SetDialogltemText(myltemHandle, myString) ;
}
Our application's resource file contains a 'STR#' resource of ID k0perationsStringsResID that contains strings describing each of the 12 possible operations our movie progress function can be called to handle. We'll use the same strings that are used in the default progress dialog box. (In fact, I simply "borrowed" the 'STR#' resource of ID -19183 from the QuickTime extension.) Our custom progress function is in fact fairly simple in structure, if a tad long. It simply inspects the theMessage parameter to see what phase of the operation is occurring and then switches to the appropriate code to handle
136
Chapter5 In and Out
that phase. W h e n our function receives the movieProgressOpen message, it opens our custom progress dialog box and performs any initial configuration of the dialog box. W h e n it receives the movi eProgressUpdatePercent message, it updates the progress bar control and erases the appropriate section of the picture in the dialog box. During this phase, our progress function also looks to see if the user wants to cancel the operation. Finally, w h e n it receives the movieProgressClose message, it disposes of the dialog box and cleans up. Let's consider each of these phases in a bit more detail.
Opening the Dialog Box When our custom progress function receives the movi eProgressOpen message, we'll open a dialog box in the standard way, by reading it from our resource file: myDialog = GetNewDialog(kProgressDialogResID, NULL, (WindowPtr)-l) ;
If we are successful in opening the dialog box (that is, if myDi a log is nonNULL), then we need to display the appropriate operation message (which we just saw how to do) and configure the progress bar control. To configure the control, we want to set its m i n i m u m value to 0 and its m a x i m u m value to some arbitrary value, defined by the constant kProgressBarMaxVal ue: GetDialogltem(myDialog, kProgressBarltemID, &myltemKind, &myltemHandle, &myI temRect) ; myBar = (ControIHandle)myltemHandle; SetControIMinimum(myBar, O) ; SetControIMaximum(myBar, (SInt16) kProgressBarMaxVal ue) ;
In fact, we could probably dispense with calling SetControlMinimum and SetContr01Maximum here, because the m i n i m u m and m a x i m u m values are also set in the resource file; but it d o e s n ' t hurt to make sure that those values are what we expect them to be. W h e n it comes time to update the progress bar control, it will be important that the control m a x i m u m be set correctly. Note that we are saving the control handle of the progress bar control in the local static variable myBar. Next, we need to set a drawing procedure for the user item that contains the progress picture. We can do so like this: GetDialogltem(myDialog, kProgressPictureltemlD, &myltemKind, &myltemHandle, &myI temRect) ; SetDialogltem(myDialog, kProgressPictureltemID, myltemKind, (Handl e) gProgressUser I temProcUPP, &myI temRect) ;
Custom Progress Functions 137
The global variable gProgressUserltemProcUPP is a universal procedure pointer to our function QTDX_ProgressBoxUserItemProcedure, which reads the picture from a 'PICT' resource in our application's resource file and draws it in the rectangle enclosing the user item, using the QuickDraw function DrawPicture. Now we are ready to display our custom progress dialog box to the user. We'll call MacShowWindow and DrawDialog to do so. We shall also call the useritem drawing procedure directly, since that results in a noticeably quicker update of the user item when the box is first drawn. MacShowWindow(myDial og) ; QTDX_ProgressBoxUserltemProcedure(myDial og, kProgressPi cturel temID) ; DrawDial og (myDial og) ;
Finally, we'll call the TickCount function to get the current time, so that we can later display an estimate of the remaining time: myTicks = TickCount();
Handling Progress Messages When our custom progress function receives a movieProgressUpdatePercent message, the thePercentDone parameter indicates the percentage of completion. As mentioned earlier, the value passed in the thePercentDone parameter is always between 0 and fixed1 (that is, between OxO0000000 and OxO0010000). Just to be safe, however, we'll first verify that the value passed to our custom progress function lies within the expected range: i f ((thePercentDone < O) [[ (thePercentDone > fixed1)) break;
The next thing we want to do is update the progress bar control. Remember that the acceptable values for that control lie between 0 and kProgressBarMaxValue, so we need to scale thePercentOone to lie within that range. We can do this with the following lines of code: i f (myBar I: NULL) { SetControIValue(myBar, (SInt16)Fix2Long(FixMul (thePercentDone, Long2Fi x (kProgressBarMaxVal ue) ) ) ) ;
}
We also want to erase the appropriate bottom portion of the picture in the custom dialog box. Once again, this mainly involves scaling the height of the picture rectangle by the percentage we are passed, as follows:
138
Chapter5 In and Out
GetDialogltem(myDialog, kProgressPictureltemID, &myltemKind, &myltemHandle, &myI temRect) ; MacSetRect (&myEraseRect, myItemRect, l e f t , myltemRect.bottom - (SInt16)Fix2Long(FixMul (thePercentDone, Long2Fi x (myI temRect, bottom - myI temRect, top) ) ), myl temRect, right, myl temRect, bottom) ; EraseRect (&myEraseRect) ;
The final visible thing we want to do is print out an estimated time remaining in the operation. In OTDX_MovieProgressProc, we retrieve the rectangle surrounding the area where we want to draw the remaining time estimate and then call the function OTDX_EstimateRemainingTime, like this: GetDialogltem(myDialog, kProgressTimeltemID, &myltemKind, &myltemHandle, &myI temRect) ; QTDX_EstimateRemainingTime(&myltemRect, thePercentDone, TickCount() - myTicks); QTDX_EstimateRemaini ngTime is defined in Listing 5.8.
Listing 5.8 Displaying the estimated time remaining. void QTDX_EstimateRemainingTime (Rect *theRect, Fixed thePercentDone, UInt32 theTi cksEl apsed) char Fixed UInt32 Rect StringPtr
myStri ng [321 ; myEstTicks; myRemSeconds; myEraseRect; myPStri ng = NULL;
myEstTicks = FixMul (FixDiv(fixedl, thePercentDone), Long2Fix(theTicksElapsed)) ; myRemSeconds = Fix2Long(FixDiv(myEstTicks - Long2Fix(theTicksElapsed), Long2Fix(60))) ; TextSi ze (kTimeRemaini ngLabel Si ze) ; TextFont (1) ; myPString = QTUtiIs ConvertCToPascalString(kTimeRemainingLabel) ;
MoveTo(theRect->left, theRect->bottom) ; DrawStri ng (myPStri ng) ;
Custom Progress Functions 139
MacSetRect (&myEraseRect, theRect->left + StringWidth(myPString), theRect->top, theRect->right, theRect->bottom) ; free(myPStri ng) ; EraseRect (&myEraseRect) ; MoveTo(myEraseRect.left, myEraseRect.bottom) ; / / the early percentages give inaccurate estimates, so don't start displaying the / / time until we've reached a minimum threshold i f (thePercentDone < kMinimumUsefuIPercent) return; i f (myRemSeconds == I) sprintf(myString, "~ou second", myRemSeconds); else sprintf(myString, "~ou seconds", myRemSeconds); myPString = QTUtils ConvertCToPascaIString(myString) ; DrawString (myPStri ng) ; free(myPStri ng) ;
Handling User Actions One other thing we need to do in response to the movieProgressUpdatePercent message is to check to see w h e t h e r the user has performed any actions that affect any items in our custom progress dialog box. In our case, that means that we have to check to see w h e t h e r the user has clicked the Stop button or pressed an equivalent key or key combination. This turns out to be a bit tricky. Normally, w h e n we are displaying a modal dialog box, we can sit in a loop calling the Modal Di a log function, waiting for the user to hit the Stop button (or perform some other operation that our modal dialog event filter function will map into a click on the Stop button). But we cannot adopt that strategy here, because our custom progress function is being called periodically by the Movie Toolbox, which is busy performing some lengthy operation. In other words, w e ' r e not in charge w h e n we're inside of our progress function; rather, the Movie Toolbox is allotting us some time periodically to update our progress dialog box. Since we cannot sit around waiting for the user to perform some relevant action, the next best thing we can do is go looking for events that interest us
140
Chapter 5 In and Out
w h e n e v e r we receive a movieProgressUpdatePercent message. For instance, we can look for clicks on the Stop button by searching the event queue for mouse-down events, like this: GetDi al ogl tem(myDial og, kProgressStopButtonl temID, &myltemKi nd, &myltemHandle, &myltemRect) ; i f (WaitNextEvent(mDownMask, &myEvent, O, NULL)) { GlobaIToLocal (&myEvent.where) ; i f (TrackControl ((ControlHandle)myItemHandle, myEvent.where, NULL)) myErr = userCanceledErr;
}
And we can look for key presses by searching the event q u e u e for keyDown events, like this: i f (WaitNextEvent(keyDownMask, &myEvent, O, NULL)) { myKey = myEvent.message & charCodeMask; i f (myEvent.modi fiers & cmdKey) i f (IsCmdChar(&myEvent, kPeriod)) myKey = kEscapeKey; i f (myKey == kEscapeKey) { uns i gned l ong myTi cks; / / simulate a click on the Stop button Hi I iteControl ((ControIHandle)myltemHandle, kControl ButtonPart) ; Delay(kMyButtonDelay, &myTicks) ; HiliteControl ((ControIHandle)myltemHandle, false) ; myErr = userCanceledErr;
Notice that w h e n we find a click on the Stop button or the appropriate key press, we set our function return value to userCanceledErr. W h e n e v e r our custom progress function returns any nonzero value, the Movie Toolbox cancels the operation in progress. Now, this all works fairly well for handling user actions. Our progress function is called often enough that it can pick up these user actions and respond to them just about as quickly as if it were continually calling ModalDialog inside a loop. There is only one remaining complication: if we run our application with this code for our custom progress function on Windows, the user's clicks on the Stop button will not be found w h e n we call WaitNextEvent. {This is due to some fairly low-level details of the QuickTime
Custom Progress Functions '1141
Media Layer, which need not concern us here.) The Escape key presses will be found just fine, and all the item-updating code works just fine. It's just that clicks on the Stop button are not to be found in the event queue. The solution to this problem is to install a callback procedure that is executed whenever an event occurs for one of the active control items in the custom dialog box. Our callback function can be very simple: all it needs to do is look for clicks on the Stop button and then set a flag to pass that information back to our custom progress function. Listing 5.9 shows our dialog callback function. Listing 5.9 Looking for clicks on the Stop button on Windows. # i f TARGET OS WIN32 static void QTDX_ModelessCallback (EventRecord *theEvent, DialogPtr theDialog, short theltemHit)
{
#pragma unused(theEvent, theDialog)
}
i f (theltemHi t == kProgressStopButtonltemID) gUserCancelled = true;
#endif
Now we need to do two other things. In the code handling the movieProgressOpen message, we need to install this callback procedure and initialize the global flag, like this: # i f TARGET OS WIN32 SetModel essDi aI ogCaI I backProc (myDial og, (QTModelessCal I backUPP)QTDX_ModelessCal I back) ; gUserCancel I ed = false; #endi f
And then in our code that handles the movieProgressUpdatePercent message, we need to see w h e t h e r the global flag has been set by the callback procedure; if so, we set the function return value to some nonzero value and then jump to the end of the routine. # i f TARGETOS WIN32 i f (gUserCancelled) { myErr = userCancel edErr; goto bai I ; m
}
#endi f
142
Chapter 5 In and Out
If you'd prefer to avoid using global variables here, you could instead pass information to and from the callback procedure by setting the w i n d o w reference constant of the custom progress dialog box, using the SetWRefCon function.
Closing the Dialog Box W h e n the Movie Toolbox is finished with the operation that triggered our progress function or w h e n it receives a nonzero return value from our progress function, it sends our progress function a moviePr-ogressClose message. This is our signal to remove our custom progress dialog box from the screen and do any other necessary cleanup. Our custom progress function executes these few lines to dispose of our dialog box and reset the static variables: case movieProgressCl ose: i f (myDialog l= NULL) Di sposeDi al og (myDial og) ; myDial og = NULL; myBar = NULL; break;
So now we've handled all three messages. Our complete progress function is shown in Listing 5.10. Listing 5.1t:) Displayinga custom movie progress dialog box. PASCAL_RTN OSErr QTDX_MovieProgressProc (Movie theMovie, short theMessage, short theOperation, Fixed thePercentDone, long theRefcon)
{
#pragma unused(theMovie, theRefcon) CGrafPtr GDHandle static DialogPtr static ControIHandle static UInt32 short Handle Rect Rect Str255 EventRecord char OSErr
mySavedPort = NULL; mySavedDevice = NULL; myDialog = NULL; myBar = NULL; myTicks = O; myltemKi nd; myltemHandl e = NULL; myI temRect; myEraseRect; myString; myEvent; myKey; myErr = noErr;
Custom Progress Functions 143
GetGWorl d(&mySavedPort, &mySavedDevice) ; i f (myDialog ! = NULL) SetGWorld((CGrafPtr)myDialog, GetMainDevice()) ; switch (theMessage) { case movieProgressOpen: / / display the progress dialog box myDialog = GetNewDialog(kProgressDialogResID, NULL, (WindowPtr)-l) ; i f (myDialog ! = NULL) { / / set the dialog box as the current graphics port SetGWorld((CGrafPtr)myDialog, GetMainDevice()) ; SetDi al ogCancel Item (myDial og, kProgressStopButton I temID) ; / / configure the progress bar control GetDi al ogl tem (myDial og, kProgressBar I temID, &myltemKind, &myltemHandle, &myltemRect); myBar = (ControIHandle)myltemHandle; SetControIMinimum(myBar, O) ; SetControIMaximum(myBar, (SInt16) kProgressBarMaxVal ue) ; / / set the dialog box text that describes the current operation GetDi al ogltem(myDi al og, kProgressTextltemID, &myltemKind, &myltemHandle, &myltemRect); i f ((theOperation > O) && (theOperation <= progressOpExportMovie)) { GetlndString(myString, kOperationsStringsResID, theOperation); SetDialogltemText(myItemHandle, myString) ;
}
/ / set a user-item drawing procedure for the picture rectangle GetDi al og Item(myDi al og, kProgressPi ctureltemID, &myltemKind, &myltemHandle, &myltemRect) ; SetDi al ogl tem (myDial og, kProg res sPi cture I teml D, myl temKi nd, (Handl e) gProgres sUser I temProcUPP, &myI temRect) ; / / show the dialog box and draw the picture in the user item rectangle MacShowWindow(myDial og) ; QTDX_ProgressBoxUserI temProcedure (myDiaI og, kProgressPicture I teml D) ; DrawDial og (myDial og) ;
144
Chapter 5 In and Out
myTicks = TickCount(); # i f TARGETOS WIN32 / / set a dialog callback procedure, to notify our progress proc / / that the user has cancelled SetModel essDi al ogCal I backProc (myDial og, (QTModelessCal I backUPP)QTDX_ModelessCaI I back) ; / / i n i t i a l i z e the variable that keeps track of whether the user has cancelled gUserCancel I ed = false; #endif break; case movieProgressUpdatePercent 9 # i f TARGETOS WIN32 i f (gUserCancelled) { myErr = userCanceledErr; goto bai I ;
/ / stop the operation
}
#endif / / check to see whether the user wants to cancel the operation / / get the rectangle surrounding the Stop button GetDi aI ogl tem (myDial og, kProgressStopButtonI temID, &myltemKind, &myltemHandle, &myltemRect) ; / / check for user clicks on the Stop button i f (WaitNextEvent(mDownMask, &myEvent, O, NULL)) { GlobaIToLocal (&myEvent.where) ; i f (TrackControl ((ControIHandle)myltemHandle, myEvent.where, NULL)) myErr = userCanceledErr; / / stop the operation
}
/ / check for user presses on the Escape key or on equivalent key combinations i f (WaitNextEvent(keyDownMask, &myEvent, O, NULL)) { myKey = myEvent.message & charCodeMask; i f (myEvent.modi fiers & cmdKey) i f (IsCmdChar(&myEvent, kPeriod)) myKey = kEscapeKey; i f (myKey : : kEscapeKey) { unsigned l o n g myTicks;
Custom Progress Functions 145
/ / simulate a click on the Stop button Hi I iteControl ((ControIHandle)myItemHandle, kControl ButtonPart) ; Delay(kMyButtonDelay, &myTicks) ; HiliteControl ((ControIHandle)myItemHandle, false) ; myErr = userCanceledErr;
/ / stop the operation
/ / update our progress dialog box i f (myBar != NULL) { / / thePercentDone is in the range 0 to fixed1 (OxO0000000 to OxO0010000); / / we need to scale i t to l i e within the range 0 to kProgressBarMaxValue SetControIValue(myBar, (SInt16)Fix2Long(FixMul (thePercentDone, Long2Fi x (kProgressBarMaxVal ue) ) ) ) ;
}
/ / erase the appropriate bottom portion of the picture GetDi al ogltem(myDi al og, kProgressPi ctureltemID, &myltemKind, &myltemHandle, &myItemRect); MacSetRect ( &myEraseRect, myI temRect. I eft, myI temRect.bottom (SInt16) Fi x2Long(Fi xMul (thePercentDone, Long2Fi x (myl temRect .bottom - myI temRect, top) ) ), myltemRect, right, myl temRect, bottom) ; EraseRect (&myEraseRect) ; / / update the estimated time remaining GetDialogltem(myDi alog, kProgressTimeltemID, &myltemKind, &myltemHandle, &myltemRect); QTDX_EstimateRemainingTime(&myltemRect, thePercentDone, TickCount() - myTicks) ; break; case movieProgressCl ose: / / remove our progress dialog box i f (myDialog ! = NULL) Di sposeDi aIog (myDiaIog) ; myDial og = NULL; myBar = NULL; myTicks = O;
146
Chapter 5 In and Out
}
break;
bail 9 SetGWorld(mySavedPort, mySavedDevice); return (myErr) ;
Progress Functions for Image Operations So far, we've focussed on implementing a custom progress function for operations involving movies (importing, exporting, cutting, pasting, and so forth). But operations on images can also take a significant a m o u n t of time. For instance, compressing or decompressing an image can sometimes take quite a while, especially if the compression or decompression algorithm is processor-intensive and the image is fairly large. So w e ' d like to be able to provide the same sort of progress notification to the user that we can now provide with lengthy operations on movies. We can do this by defining an
image progress function. In general, everything we've learned so far about movie progress functions will be of use in writing an image progress function. The declaration of an image progress function is slightly different than that of a movie progress function. Here's how we might declare an image progress function: PASCAL_RTN OSErr QTDX_ImageProgressProc (short theMessage, Fixed thePercentDone, long theRefCon);
As you can see, there is no parameter specifying the movie (since, of course, there is no movie being operated upon here). Also, there is no indication of which operation is triggering our image progress function. The main difference between an image progress function and a movie progress function is in the way we install the progress function. As we've seen, we can call SetMovieProgressProc to install a movie progress function for lengthy operations involving a movie. W h e n we call SetMovieProgressProc, we need to pass it a universal procedure pointer to the movie progress function. When installing an image progress function, however, we instead need to pass the address of a structure of type I CMProgressProcRecord, which is defined (in ImageCompression.h) like this: struct ICMProgressProcRecord { ICMProgressUPP progressProc; long progressRefCon;
};
Progress Functions for Image Operations 147
Using the ICMProgressProcRecord record, we specify both the image progress function and the reference constant. For example, we could call GraphicsImportSetProgressProc to install an image progress function for any image handled by our application like this: i f ((**theWindowObject).fGraphicslmporter ! = NULL) { I CMProgressProcRecord myProcRec; myProcRec,progressProc = glmageProgressProcUPP; myProcRec,progressRefCon = (l ong) theWi ndowObject; Graphi cs ImportSet Progress Proc ( (**t heWindowObject). fGraphi cs Importer, &myProcRec) ;
At this point, whenever the graphics importer associated with the image undertakes some lengthy operation, it will call our image progress function OTDX_ImageProgressProc. (To get the default image progress function, pass (ICMProgressProcRecordPtr)-I as the second parameter, in place of &myProcRec.) We could of course display a custom progress dialog box devoted especially to images and manage that dialog box with a new image progress function; for simplicity, however, we'll just call our existing movie progress function, as shown in Listing 5.11.
Listing 5.11 Displayinga custom image progress dialog box. PASCAL_RTN OSErr QTDX_ImageProgressProc (short theMessage, Fixed thePercentDone, 1ong theRefCon)
{ }
return(QTDX_MovieProgressProc(NULL, theMessage, O, thePercentDone, theRefCon));
Notice that we pass NULL for the movie parameter (which is OK since we never use that parameter in the custom movie progress function}. We also pass 0 as the operation parameter. As I mentioned earlier, our custom image progress function does not get notified about which operation is taking a long time; accordingly, we just pass 0 to our movie progress function as the operation parameter. Since 0 is not a valid index in a 'STR#' resource, we won't be able to display a custom message telling the user which operation is in progress. For images, therefore, the custom progress dialog box will contain whatever message is specified in the dialog item resource {which in our case is "Making Progress").
148
Chapter 5 In and Out
T h e Code The code folder accompanying this chapter contains the project files, source code, and resource data of a sample application called QTDataEx, for both Macintosh and Windows. QTDataEx is just like our basic QTShell application, except that the Test menu has been renamed "Movie" and includes three items that illustrate basic uses of movie data exchange components. Figure 5.8 shows the Movie menu of QTDataEx w h e n a QuickTime movie is in the frontmost window.
Figure 5.8
The Movie menu in QTDataEx.
Choosing one of these items results in our application calling one of the functions we've defined earlier (that is, either QTDX_ImportAnyNonMovie, QTDX_ ExportMovieAsAnyTypeFile, or QTDX_ExportMovieAsHintedMovie). Further, the function QTApp_SetupWindowObject installs our custom movie and image progress functions so that any lengthy operations involving movies or images opened by our application will result in the display of our custom progress dialog box. For import operations, where there is no movie initially available, we need to specify the custom progress function as a parameter to the ConvertFileToMovieFile function (see Listing 5.7).
Conclusion In this chapter we've taken a preliminary look at using movie importers and exporters. We've used the high-level functions ConvertFileToMovieFile and ConvertMovieToFile to perform some basic importing and exporting. We've also worked directly with movie exporters when displaying an exporter's settings dialog box (with MovieExportDoUserDi al og) and managing the settings in that dialog box (with MovieExportGetSettingsAsAtomContainer and MovieExportSetSettingsFromAtomContainer). And we've seen how to display and manage the default and custom progress dialog boxes for both movies and images. QuickTime provides a wide array of lower-level importing and exporting capabilities. If we wanted to export only part of a movie, for instance, we could use the MovieExportToFile function. Or, if we wanted to export a movie into memory (and not into a file), we could use the MovieExportToHandle function. As usual, we've barely scratched the surface with movie importers and exporters.
Conclusion
1149
This Page Intentionally Left Blank
Doug's 1st Movie Creating QuickTime Movie Files
Introduction So far in this book, we've learned how to open movie files and allow the user to interact with the movies in those files. We've learned how to perform some basic operations on movies, such as editing them and exporting them under new formats. We've also learned how to open and display image files and to perform some simple transformations on those images. And, for good measure, we've managed to do everything in a fully cross-platform manner so that our applications run both under the Macintosh operating system and under Windows, with exactly the same features. Now it's time to take an important step forward in our journey through QuickTime: it's time to learn how to create QuickTime movie files. Even though QuickTime supports a vast array of types of media (audio, video, text, sprite animation, vector image, virtual reality, and so forth), it expects that all of the media data and the information describing that data will be stored in a specific format, called the Q uickTime movie lile format. This means that once we learn the basic sequence of operations involved in creating files that adhere to this format, we can fairly easily apply that knowledge to create files containing any of these types of media data. For the moment, we're going to restrict our attention to creating a QuickTime movie file with a single video track. But the techniques we learn here will come into play over and over again in the future when we want to create movie files that contain sound data, text, music, sprites, and other types of media data. Happily, the Movie Toolbox provides a set of high-level programming interfaces that we can use to create movie files without having to know very much about the actual details of the QuickTime movie file format. We need to know some of those details, however, so we'll begin by surveying the structure of QuickTime movies and QuickTime movie files. Then we'll be ready to create movie files that exhibit that structure.
151
1"he Structure of Quick'rime M o v i e s What exactly is a QuickTime movie? There are really two answers to this question. So far in this book, we've been concerned primarily with QuickTime movies as they exist in memory. That is to say, we've been working with items of type Movie that we can play, edit, attach movie controllers to, and so forth. We typically obtain these movies by opening Quick Time movie files, which exist on disk (or some other storage medium). The movie file contains the audio and video data that is presented to the user w h e n a movie is being played, as well as other information (called metadata) that describes how that audio and video data is organized and synchronized. Of course, QuickTime isn't limited to playing audio and video data, so we'll need a more general term to refer to the movie data contained in the movie file; let's call it media data. As a rough preliminary characterization, then, we can say that a QuickTime movie file is a file that contains the movie's media data and the associated metadata. (As we'll see later, a movie file might not actually contain the media data, but only references to the media data. For the moment, however, we'll ignore this possibility.) A QuickTime movie, on the other hand, is a structure that contains information about the media data. In effect, a QuickTime movie is just a bookkeeping device that contains the information necessary to retrieve the media data from the QuickTime movie file and present it to the user at the appropriate moment. The exact structure of QuickTime movies is private. If you take a look into the header file Movies.h, you'll see that a variable of type Movie is a pointer to a MovieRecord structure, which is defined like this: struct MovieRecord { long
};
data[l] ;
All we can tell about the structure of a MovieRecord is that it contains at least 4 bytes of data. We can operate on movies only by using the application programming interfaces provided by the Movie Toolbox. A movie consists of one or more tracks, plus some optional movie user data. A track has a starting time and duration and is associated with exactly one kind of media data. So, for instance, a track might hold audio data or video data, but not both. A movie can contain several tracks, each associated with a different kind of media data. Also, a movie can contain several tracks that are associated with the same kind of media data. For instance, a movie might have a video track and several audio tracks (perhaps in different languages).
152
Chapter6 Doug's 1st Movie
The structure of a track is also private. A variable of type Track is a pointer to a TrackRecord structure, which is defined like this: struct TrackRecord { long
};
data[l] ;
A track contains a single media structure (or, more briefly, a media), w h i c h references, but does not contain, the media data associated with the track. Once again, as you've probably guessed, the structure of a media is private. A variable of type Media is a pointer to a MediaRecord structure, w h i c h is defined like this: struct MediaRecord { long
};
data[I];
Figure 6.1 shows a standard way of depicting the structure of a QuickTime movie. As you can see, this movie contains three tracks: two video tracks and one sound track. Associated with a movie is a movie time coordinate system, which provides a means to measure time in a movie. The basic unit of time m e a s u r e m e n t for a movie is the movie's time unit, and the number of time units that elapse per second is the movie's time scale. In the movie shown in Figure 6.1, the time scale is 600, so the time unit is 1/600th of a second. The sound track is scheduled to begin playing after 1 second has elapsed in the movie, and video track 2 is scheduled to begin playing after about 2 seconds have elapsed. QuickTime requires that all tracks start at time 0, but the track data can begin later in the movie; the e m p t y space between the beginning of the movie and the beginning of the track data is called the track offset.
Figure 6.1
The structure of a QuickTime movie.
The Structure of QuickTime Movies
1153
Keep in mind that Figure 6.1 is intended to illustrate the logical structure of a QuickTime movie, not the actual arrangement of bytes in memory. To repeat, the actual structure of a QuickTime movie in m e m o r y is private. The only way to operate on movies, tracks, or media is to use the APIs provided by the Movie Toolbox.
T h e Structure of Q u i c k T i m e M o v i e Files In contrast to the undocumented, private structure of QuickTime movies, the structure of QuickTime movie files is completely public. This means, among other things, that QuickTime movie files can be built on any operating system, whether or not the QuickTime software is available on that operating system. That's because a QuickTime movie file is just a sequence of bytes structured according to an openly documented specification. Note, however, that you don't actually have to know the details of that specification to build QuickTime movie files. The Movie Toolbox provides a set of high-level functions that we can use to build QuickTime movie files with a minimum of fuss. (Whew!) Nevertheless, it will be useful for us to become acquainted with at least some of those details, if only to understand better what it is we are building and why we need to do certain things when building QuickTime movie files. So let's take a quick look at the structure of QuickTime movie files. It turns out that the basic structure of QuickTime movie files has evolved in the years since QuickTime was introduced. Files created back then will still play OK nowadays {at least on Macintosh computers}, but we can make life easier for ourselves and our viewers if we build files that conform to the currently preferred format, which is single-fork, self-contained, Fast Start, interleaved movie files. Let's unravel that mouthful.
Double-Fork and Single-Fork Movie Flies When QuickTime was first released, back in 1991, it ran only on the Macintosh operating system. Accordingly, the default behavior of the Movie Toolbox was to build movie files that took advantage of the dual-fork nature of files in the Macintosh file system, where each file has both a resource fork and a data fork. The movie's metadata was stored in the resource fork and the movie's media data was stored in the data fork. This clean separation of metadata from media data meant that the Movie Toolbox could very easily find the metadata, parse it, and load it into m e m o r y as a QuickTime movie, without ever touching the media data. Figure 6.2 shows the original structure of QuickTime movie files as double-fork files. Figure 6.2 also reveals a bit more about the internal structure of the data and resource forks of a double-fork QuickTime movie file. Consider first the
154
Chapter6 Doug's 1st Movie
Figure 6.2
A double-fork movie file.
data fork. The media data is contained in a structure called an atom. An atom is simply a collection of data preceded by an atom header, w h i c h consists of a 4-byte length value and a 4-byte type. (The length value includes the 8 bytes occupied by the atom header.) In this case, the atom is a movie data atom, whose type is 'radar'. The data contained in a movie data atom is one or more media samples, which together comprise the movie's media data. A media sample is a single element of movie data. (You can think of a video frame as a single sample.) Now let's turn our attention to the resource fork in Figure 6.2. As you can see, the resource fork contains both a resource header and a resource m a p (which are contained in every well-formed Macintosh resource file). The resource fork also contains a resource of type 'moor', which is called the movie resource. The movie resource contains the movie metadata, w h i c h - - l o and behold--is structured as an atom of type 'moor'. This atom is called the movie atom. The main problem with double-fork movie files is that they cannot easily be transported to operating systems that do not support resource forks. To facilitate cross-platform deployment of multimedia content, QuickTime also supports single-fork movie files. In this case, the movie media data and the movie metadata are stored in one file (which is the data fork on Macintosh systems). ~ p i c a l l y , the movie atom is simply appended to the end of the movie data atom, as shown in Figure 6.3. This movie file can be opened and played back on any operating system that supports the QuickTime playback software. As a result, we shall always build single-fork movie files w h e n e v e r we create QuickTime movie files. Before we move on, let's take a m o m e n t to try to prevent some potential confusion. As we've just seen, both single- and double-fork movie files store the movie metadata in an atom of type 'moor', called the movie atom. In a double-fork movie file, the movie atom is contained in a resource of type 'moor ~ called the movie resource. Indeed, in a double-fork movie file, the
The Structure of QuickTime Movie Files 155
Figure 6.3 A single-fork movie file.
movie atom and the movie resource are identical. This fact has encouraged some developers to use the terms "movie resource" and "movie atom" interchangeably. But this is unfortunate, since (as you can see) there is no movie resource in a single-fork movie file, but there is a movie atom. The potential for confusion is c o m p o u n d e d by the fact that the Movie Toolbox includes the function AddMovieResource, which we will need to call to add the movie atom to our single-fork movie files (see, for instance, Listing 6.1). Originally, QuickTime did not provide a way to create single-fork movie files directly. Instead, you had to create a double-fork movie file and then call the function FlattenMovieData to make a single-fork copy of that double-fork movie file. In QuickTime 3.0, AddMovieResource was revised to support direct creation of single-fork movie files. Nowadays, AddMovieAtom would perhaps be a better name than AddMovieResource.
Fast S t a r t M o v i e Files Notice that, according to the default structure of single-fork movie files (as shown in Figure 6.3), the movie atom is stored at the end of the file. The reason for this is quite simple. Typically, we build a new QuickTime movie file by creating an empty movie file, adding new tracks to the movie, adding a new media to the track, and then adding some media samples to the media. As this process continues, the Movie Toolbox keeps track of the gradually changing metadata, which can be added to the movie file only after all the movie data has been added. The movie metadata is rather like a cargo manifest, which can be deemed accurate only after all the cargo has been loaded. In some cases, this default location of the movie atom is unproblematic. When the movie file is local (that is, stored on a local hard disk, CD-ROM, or other random-access storage device), QuickTime can search through the file quickly enough that it can find the movie m e t a d a t a - - w h i c h it needs in order to start playing the movie--with no appreciable delay. But w h e n the movie file is being sent across a local area network, or indeed across the Internet, it isn't generally possible to randomly access the file's data in this manner. This means that QuickTime cannot start playing remotely stored movies until the entire movie has been downloaded from the remote storage device to the local playback machine.
156
Chapter 6 Doug's 1st Movie
To remedy this situation, QuickTime provides support for creating Fast Start movie files, in which the movie atom is stored as the first atom in a single-fork movie file. Figure 6.4 shows the structure of a Fast Start movie file. As you can see, the only difference between a Fast Start movie file and a default single-fork movie file is the location of the movie atom. This simple change, however, is enough to enable QuickTime to start playing movies served from the Web via HTTP or FTP before the entire movie has downloaded.
Figure 6.4 A Fast Start movie file. To create a Fast Start movie file, we need to create a single-fork movie file and t h e n call VlattenMovieOata with the flattenForceMovieaesourceBeforeMovieData flag. We'll see how to do this later.
R e f e r e n c e a n d S e l f - C o n t a i n e d M o v i e Files Earlier, I warned that a movie file might not actually contain the movie's media data, but only references to the media data, which is contained in some other file (called the media lile). A file that has this characteristic is called a reference movie file. Figure 6.5 illustrates this possibility. Here, the movie file itself contains only the movie atom, which contains references to the media data. Reference movie files can be useful if you want to share some data among two or more QuickTime movies. By referencing the shared media data instead of containing copies of it, the associated QuickTime movie files can take up substantially less space.
Figure 6.5 A reference movie file and its target media file. The Structure of QuickTime Movie Files 1 5 7
It's also possible for a reference movie file to refer to media data in more than one media file. Indeed, it's possible for a reference movie file to refer to media data in some media file as well as media data contained in the reference movie file itself. {The first kind of media reference is called an external reference, and the second kind is called an internal reference.) QuickTime really doesn't care w h e r e the media data is stored, as long as it can resolve the references to that data at playback time. The opposite of a reference movie is a self-contained movie/ile. In a selfcontained movie file, all the media data needed for playing the movie is contained in the movie file itself. Or, put another way, a self-contained movie file does not depend on any other files. Put yet another way, all media references in a self-contained movie file are internal references. Figure 6.6 shows a self-contained movie file, in w h i c h the media references in the movie atom are resolved to media data in the movie file itself.
Figure 6.6
A self-contained movie file.
If we've got a reference movie file, we can create a self-contained movie file from it by calling FlattenMovieData. {Note, however, that it's possible to build a self-contained movie file directly, without having to create a reference movie file and then call FlattenMovieData to create another movie file.) FlattenMovieData resolves all media references and copies the referenced data into the movie file itself. For this reason, a self-contained movie file is sometimes also called a flattened movie file. But this terminology can be confusing, since FlattenMovieData also makes copies of any media data that is multiply referenced by internal media references. That is to say, if a self-contained movie file contains several internal references to the same media data, then the result of calling FlattenMovieData on that file will be a larger movie file that contains several copies of the referenced media data (each of which is referred to exactly once by the movie atom). So, if we reserve the term "flattened" for any movie files that might have been created by FlattenMovieData, it follows that not all self-contained movie files are flattened movie files. To make matters worse, the term "flattening" is sometimes also used to refer to the process of converting a double-fork movie file into a single-fork movie file. So, in this parlance, a flattened movie file is simply any single-
158
Chapter 6 Doug's 1st Movie
fork movie file, whether or not it contains any external media references. Perhaps the best course of action is simply to avoid using the term "flattened" altogether.
I n t e r l e a v e d a n d N o n - i n t e r l e a v e d M o v i e Files We've almost reached the end of our survey of QuickTime movie file organizations. There is only one final twist that we need to consider. Typically, w h e n we build a movie file that contains more than one kind of media data, we add the media samples for one kind of media data [for example, video data) and then we add the media samples for another kind of media data (for example, audio data). The resulting file is a non-interleaved movie file, as shown in Figure 6.7. Non-interleaved movie files do not provide optimal playback from slower storage devices {such as CD-ROMs), where seeking can be expensive, or in situations [such as network playback) where random access to the file data is not possible. Instead, it's better to reorganize the media data so that it's arranged in temporal order. That is to say, we'd like the audio and video data for the first second of the movie to be stored close to one another, followed by the audio and video data for the next second of the movie, and so forth. Figure 6.8 shows an interleaved movie tile that has the desired structure. To create an interleaved movie file, we typically create a single-fork movie file and then call F] attenMovieData. By default, F] attenMovi eData interleaves the media data to ensure optimal movie playback. You can override this default behavior by passing the f]attenDontInter]eaveF]atten flag to F]attenMovieData; the result would be a self-contained, non-interleaved movie file.
Figure 6.7
A non-interleaved movie file.
Figure 6.8
An interleaved movie file.
The Structure of QuickTime Movie Files 1 5 9
CreatJng QuiclCTJme Movie Files Our ultimate goal, then, is to create a single-fork, self-contained, Fast Start, interleaved movie file. The resulting file will play on all platforms that support QuickTime movie playback and be suitable for distributing on CDROM and over the Internet. To simplify things, we're going to create a movie file that contains a single video track. We'll postpone adding other kinds of tracks to future chapters. To create a single-fork, self-contained QuickTime movie file, we typically need to perform eight operations, in this order: 1. Create a new, empty movie file and a movie that references that file (CreateMovi eFi I e).
2. Add a new track to that movie (NewMovieTrack). 3. Add a new media to that track (NewTrackMedia). 4. Add media samples to the media. 5. Insert a reference to the media segment into the track at the desired offset (InsertMedi alntoTrack).
6. Add the movie atom to the movie file (AddMovieResource). 7. Close the movie file (Cl oseMovieFi I e). 8. Dispose of the movie (Di sposeMovie). If we want the final movie file to be either Fast Start or interleaved, we need to perform one additional operation: 9. Place the movie atom as the first atom in the movie file, and interleave the media data (FI attenMovieData). As you can see, each of these steps--except for step 4--can be accomplished with a single Movie Toolbox function. We're going to use these eight functions, in this order, over and over again as we build different kinds of QuickTime movie files, here and in future chapters. So you should take a moment to burn these steps into your memory. The only real differences between building, say, a video movie file and a wired sprite movie file concern step 4, adding media samples to the media. Even though the movies in those two kinds of files have radically different playback characteristics, the fundamental structure of the QuickTime movie files is the same, and so the way we build those files will be essentially the same. Let's take a preliminary look at how this all comes together in practice. Listing 6.1 defines the function OTMM_CreateVideoMovie, which is the routine used by our sample application QTMakeMovie for building a QuickTime movie file. QTMM_CreateVideoMovie begins by calling the framework function
160
Chapter6 Doug's 1st Movie
QTFrame_PutFile to elicit from the user a filename and location for the new movie file. Then QTMM_CreateVideoMovie calls the Movie Toolbox functions just listed to build a movie file. Step 4, adding media samples to the media, is handled by the application function QTMM_AddVideoSampl esToMedi a, which is sandwiched between the t w o calls Begi nMedi aEdi ts and EndMediaEdi ts.
Listing 6.1 Creating a QuickTime movie. OSErr QTMM_CreateVideoMovie (void) Movie Track Medi a FSSpec Boolean Boolean StringPtr StringPtr long short short OSErr
myMovie = NULL; myTrack = NULL; myMedia = NULL; myFile; myI sSel ected = false; mylsReplacing = false; myPrompt = QTUti I s ConvertCToPascal Stri ng (kNewMoviePrompt) ; myFi I eName = QTUti I s_ConvertCToPascaI St r i ng( kNewMovieFi I eName) ; myFlags = createMovieFileDeleteCurFile I createMov i eFi I eDontCreateRes Fi I e; myResRefNum = O; myResID = movielnDataForkResID; myErr = noErr;
/ / prompt the user for new filename QTFrame_PutFile(myPrompt, myFileName, &myFile, &mylsSelected, &mylsReplacing) ; myErr = mylsSelected ? noErr 9userCanceledErr; i f (myErr l= noErr) goto bai I ; / / create a movie f i l e for the destination movie myErr = CreateMovieFile(&myFile, sigMoviePlayer, smCurrentScript, myFlags, &myResRefNum, &myMovie); i f (myErr l= noErr) goto bai I ; / / create the movie track and media myTrack = NewMovieTrack(myMovie, Fi xRati o (kVi deoTrackWi dth, 1), Fi xRati o (kVi deoTrackHei ght, 1), kNoVoI ume) ; myErr = GetMoviesError() ; i f (myErr i= noErr) goto bai I ;
Creating QuickTime Movie Files 161
myMedia = NewTrackMedia(myTrack, VideoMediaType, kVideoTimeScale, NULL, 0); myErr = GetMoviesError() ; i f (myErr ! = noErr) goto bai I ; / / create the media samples myErr = BeginMediaEdits(myMedia) ; i f (myErr ! = noErr) goto bai I ; myErr = QTMM_AddVideoSamplesToMedia(myMedia, kVideoTrackWidth, kVideoTrackHeight); i f (myErr ! = noErr) goto bai I ; myErr = EndMediaEdits(myMedia) ; i f (myErr ! = noErr) goto bai I ; / / add the media to the track myErr = InsertMedialntoTrack(myTrack, O, O, GetMediaDuration(myMedia), f i x e d l ) ; i f (myErr ! = noErr) goto bai I ; / / add the movie atom to the movie f i l e myErr = AddMovieResource(myMovie, myResRefNum, &myResID, NULL); bail if if
9 (myResRefNum l= O) Cl oseMovi eFi I e (myResRefNum) ; (myMovie ! = NULL) Di sposeMovi e (myMovie) ;
free (myPrompt) ; free (myFi I eName) ; return (myErr) ;
In the following subsections, we'll gradually dissect Listing 6.1.
162
Chapter6 Doug's 1st Movie
Creating a N e w M o v i e File The first thing we need to do to create a QuickTime movie file is create a new, empty QuickTime movie file. We can do this by calling the CreateMovi eFile function, like this: myFlags = createMovieFileDeleteCurFile [ createMovieFileDontCreateResFile; myErr = CreateMovieFile(&myFile, sigMoviePlayer, smCurrentScript, myFlags, &myResRefNum, &myMovie);
Here, myFi l e is a file system specification that indicates the name and location of the new movie file. The second parameter specifies the creator type for the new file; in this case, we're passing the constant sigMoviePlayer (defined in the file Fi 1eTypesAndCreators.h) to indicate that we want the file's creator to be the QuickTime Player application (n6 MoviePlayer). Of course, you are free to use any other creator type that you wish. The third parameter specifies the script in which the movie should be created; here, as always w h e n we need to specify a script system, we pass the constant smCurrentScript. The fourth parameter to CreateMovieFi l e is a set of flags that modify the default behavior of CreateMovieFile. Generally, we will pass the two flags indicated, createMovi eFi 1eDel eteCurFi 1e and createMovi eFi 1eDontCreateResFile, which tell CreateMovieFile to delete any file already having the name and location specified by the myFi l e parameter and to create a single-fork movie file. The last two parameters allow CreateMovieFile to pass information back to us, if it successfully creates the specified movie file. In the fifth parameter, it returns to us the file reference n u m b e r for the opened movie file. (Don't let the parameter name myResRefNum fool you; because we passed the create~ MovieFileDontCreateResFile flag, the opened file fork is a data fork, not a resource fork.) CreateMovieFile accepts a flag that tells it not to open the newly created file, but here we want it to open the file so that we can add data to it. In the final parameter, CreateMovieFi l e passes back to us an identifier for a new, empty movie that references the file we just created. The parameter myMovi e is of type Movi e, which is precisely the sort of in-memory QuickTime movie that we've been using in previous chapters. From here on in, we w o n ' t do anything directly to the movie file itself. Rather, we're going to build the movie (by adding tracks and media samples to it) and then later use the AddMovieResource function to write the movie atom into the movie file.
Creating QuickTime Movie Files 163
Adding Tracks to a Movie Once w e ' v e called CreateMovieFile to create a new movie file and a new, empty movie, we need to add a track to the movie. We do this by calling the NewMovieTrack function, like this: myTrack = NewMovieTrack(myMovie, Fi xRati o (kVi deoTrackWi dth, I), FixRatio(kVideoTrackHeight, 1), kNoVolume); NewMovieTrack needs to know which movie to add the new track to; here we pass the movie identifier that we obtained from the call to CreateMovieFile. NewMovieTrack also needs to k n o w the dimensions of the new track. Since w e ' r e building a movie from scratch, we'll specify some predefined dimensions. The height and width are expected to be in units of type Fixed, so we'll use the FixRatio function to convert the predefined integer height and widths to that type. In the present case, the track is 202 pixels high and 152 pixels wide: #define kVideoTrackHeight #define kVideoTrackWidth
202 152
(These are the dimensions of a picture stored in the resource fork of the QTMakeMovie application.) The final p a r a m e t e r to NewMovieTrack is a value that specifies the desired volume level of the new track. Because the track we are about to create is a video track, we pass the constant kNoVo]ume to indicate that the volume level should be 0.
Adding a Media to a Track Recall that a track is associated with exactly one media structure (or media). The media structure contains information about the type and location of the actual media samples that comprise the QuickTime movie data. We create a new media and associate it with an existing track by calling the NewTrackMedia function, like this: myMedia = NewTrackMedia(myTrack, VideoMediaType, kVideoTimeScale, NULL, 0);
The first parameter is the track with which the new media is to be associated; here of course we use the track that we just created by calling NewMovieTrack. The second p a r a m e t e r specifies the type of media we w a n t to
164
Chapter6 Doug's 1st Movie
create. As you can see, we've used the constant VideoMediaType to specify that we want to create a new video media. The Movie Toolbox defines constants for all media types for which QuickTime supplies a media handler (that is, a component that knows how to interpret a specific kind of media data). Here are a few of the c o m m o n media types defined in Movies .h: enum { VideoMediaType SoundMediaType TextMedi aType MusicMediaType TimeCodeMediaType Spri teMediaType FlashMediaType MovieMediaType TweenMediaType
};
= = = = = = = = =
FOUR CHAR CODE( ' v i d e ' ) FOUR_CHAR_CODE(' soun ) FOUR_CHAR_CODE(' text ) FOUR CHAR CODE('musi) FOUR CHAR CODE('tmcd) FOUR_CHAR_CODE(' sprt ) FOUR CHAR CODE( ' f l s h ) FOUR CHAR CODE('moov) FOUR CHAR CODE(' twen ) D
D
Over time, we will turn our attention to each of these media types and see how to build a movie that contains media data of that type. For the m o m e n t , as you know, we're focussing on building a movie with video media data. The third parameter to the NewTrackMedi a function specifies the media time scale, which is the n u m b e r of media time units that elapse per second. The media time unit defines the media time coordinate system. The media time coordinate system is independent of the movie time coordinate system, which we discussed briefly earlier. In addition to interpreting the media data, the media handler for a track's media also manages the task of mapping values from the movie time coordinate system to the media time coordinate system. For example, w h e n the movie is ready to display a video frame, it passes the current movie time to the video media handler, w h i c h converts that time into the video media time coordinate system and then retrieves the video data at that media time. The movie time coordinate system is independent of the media time coordinate system largely to allow each media handler to work with time units that are appropriate to the kind of media it is handling. Video media often uses a time scale of 600, which is evenly divisible into the most c o m m o n frames-per-second values (8, 10, 12, 15, 24, 30, and 60). Sound media typically uses a time scale equal to the sample rate of the sound, so some comm o n sound media time scales are 11,025 (11 kHz), 22,254.54 (22 kHz), and 44,100 (44 kHz). The default QuickTime movie time scale is 600. This value was selected to facilitate the mapping between the movie time coordinate system and the
Creating QuickTime Movie Files 1G5
video media time coordinate system. Our sample application Q T M a k e M o v i e uses 600 as the video media time scale: #define kVideoTimeScale
600
/ / 600 units per second
The fourth p a r a m e t e r to NewTrackMedia specifies a media data reference, w h i c h identifies the file (or Other media container) that is to hold the m e d i a data for the specified track. Here we pass the value NULLto indicate that the media data is to be stored in the file associated with the movie (that is, the file created w h e n we called CreateMovieFi l el. It w o u l d be possible to specify some other file to hold the media data for this track; however, since we w a n t to create a self-contained file, we'll pass NULLhere. For the same reason, we pass 0 in the fifth parameter. If we were passing a non-NULL media data reference in the fourth parameter, we w o u l d use the fifth p a r a m e t e r to specify the type of data reference.
Adding Samples to a Media We've been occupied so far with creating the movie m e t a d a t a - - t h e "bookkeeping details"--that will end up inside the movie atom in the Q u i c k T i m e movie file. What we need to do now is add some media data to the movie file. The media data is w h a t the user will ultimately see or hear w h e n the movie is played and w h a t we would normally think of as the "meat and potatoes" of the QuickTime movie file. As we saw earlier, the media data is comprised of one or more media samples. To add samples to an existing media, we need to open a media editing session. That is to say, we need to inform the Movie Toolbox that we w a n t to change the media samples referenced by a track's media. We can do this by calling the Begi nMedi aEdi ts function, specifying the media we want to edit: myErr = BeginMediaEdi ts (myMedia) ;
W h e n we call BeginMediaEdits, the Movie Toolbox opens the media container, if it isn't already open, and makes sure that we can add samples to it. In the present case, the media container is the QuickTime movie file that we created w h e n we called CreateMovieFi le. Finally, w e ' v e done all the g r o u n d w o r k that we need to do before we can add some media data to our movie file. We've created a movie, a track, and a media, and w e ' v e opened a media editing session. All that remains is to call AddRediaSample one or more times to add some media samples to the media container. Unfortunately, we haven't created any media samples yet. For the m o m e n t , let's defer going into those details, so that we can spend the r e m a i n d e r of this section focussing on the overall m o v i e m a k i n g process.
1GG Chapter6 Doug's 1st Movie
Let's just call an application-defined function that adds the desired video media samples to the media" myErr = QTMM_AddVideoSamplesToMedia (myMedia, kVideoTrackWidth, kVideoTrackHeight) ;
We'll spend the entire next section, "Adding Media Samples," walking through the function QTMM_AddVideoSamp] esToMedi a. W h e n we are finished adding samples to the media, we close the media editing session by calling the EndMediaEdi ts function, like this: myErr = EndMediaEdits(myMedia) ;
Inserting a M e d i a Segment Once we've finished adding samples to the media and ended the media editing session, we need to add a reference to some or all of that media to the track. In particular, we need to specify w h e n in the track the media segment is to begin; we also need to specify the portion of the media samples to be inserted into the track. We can handle all of this with the InsertMediaIntoTrack function" myErr = I nsertMedi alntoTrack (myTrack, / / time in track O, / / beginning of media segment O, GetMedi aDurati on (myMedia), / / duration of media segment fixed1) ;
We're not doing anything fancy here, but there are a few things to keep in mind. The second parameter indicates where in the specified track the media data is to be inserted. The value of that parameter is interpreted in the movie time scale. So, if we want the video samples to start playing 2 seconds after the movie begins and if the movie time scale is 600, then we would pass the value 1200 in the second parameter. In the present case, we want the video samples to start at the beginning of the movie, so we pass 0. The second and third parameters specify the beginning and duration of the media segment to which we want to insert a reference into the target track. Both of these values should be expressed in the media time scale. Since we want to insert a reference to the entire media data, we set the beginning time to 0 and the duration to the value returned by the GetMediaDurati on function. The last parameter to InsertMediaIntoTrack indicates the media rate, which is the rate at which the media samples are to be played. We want the
Creating QuickTime Movie Files 167
samples to be played at their natural playback rate, so we pass the constant fixed1.
Adding the Movie Atom Now that we've inserted a reference to the media data into the movie's single video track, w e ' v e finally collected all the movie metadata we need, so we can add the movie atom to the QuickTime movie file. We do this by calling the AddMovieResource function, like this: myErr = AddMovieResource(myMovie, myResRefNum, &myResID, NULL);
AddMovieResource takes the information contained in the movie myMovie and creates a movie atom, which it then appends to the file specified by the myResRefNum parameter. Originally, the third and fourth parameters specified the resource ID n u m b e r and the resource n a m e for the movie resource (which, you'll recall, was added to the file's resource fork as a resource of type 'moov'). Nowadays, we are no longer interested in creating double-fork movie files, so we do not need to pass a movie resource name. Moreover, the Movie Toolbox now supports the constant movieInDataForkResID for the resource ID parameter, which indicates that the movie atom should be added to the data fork, not to the resource fork. So before we call AddMovieResource, we'll set the desired resource ID, like this: myResID = movielnDataForkResID;
Finishing Up We are essentially finished constructing a QuickTime movie file. Only two minor housekeeping tasks remain: we need to close the movie file that the Movie Toolbox automatically opened for us w h e n we called CreateMovieFi le, and we need to dispose of the movie that CreateMovieFile returned to us {and to which we subsequently added a video track). The function OTMM_ CreateVideoMovie ends with these lines of code: i f (myResRefNum != O) Cl oseMovieFi I e (myResRefNum) ; i f (myMovie I: NULL) Di sposeMovie (myMovie) ;
168
Chapter6 Doug's 1st Movie
Adding Media Samples In the previous section, we gradually dissected the function QTMM_CreateVideoMovie {defined in Listing 6.1) to learn how to create a QuickTime movie file with a video track. We postponed, however, the all-important task of adding media samples to the movie file. Instead, QTMM_CreateVideoMoviejust called the function QTMM_AddVideoSamplesToMedia, which adds some video samples to the video track's media. The reason we deferred our treatment of adding media samples is simply that a full consideration of that topic would have detracted from the main point of the previous section, which was to emphasize the general steps involved in creating any kind of QuickTime movie file. Now let's tie up the loose ends by seeing how to add some video samples to the media of the movie's track. To add a sample to a media, we really need only two things. First, of course, we need the media sample data. For a video track, the sample data usually consists of a compressed image. For a sound track, the sample data usually consists of some digitized (and possibly compressed) audio data. For a text track, the sample data consists of some n u m b e r of characters. And so forth, for all the other kinds of media supported by QuickTime. Second, we need a concise description of the kind of data contained in the media sample. The media type (specified in the call to NewTrackMedia) is generally not sufficient to allow the media handler to know how to process the media samples. For instance, a video track can contain images compressed using any one of a large number of video codecs {compressors/ decompressors}, and the track can have virtually arbitrary dimensions. For the video media handler to be able to display the video media samples correctly, it needs to know which compressor was used, the bit depth of the images, the dimensions of the images, and a handful or so of other pieces of information. The AddMediaSample function expects us to pass it this information in a structure called a sample description. The file Movies.h defines a sample description like this: struct SampleDescription { long long long short short
descSize; dataFormat; resvdl; resvd2; dataReflndex;
}; The only two fields that we usually need to fill in are descSize, which specifies the size of the sample description, and dataFormat, which specifies the codec that compressed the data. But except for some very simple media
Adding Media Samples 169
types, this structure isn't complete enough. Instead, for video media data, we'll fill in an image description, defined in ImageCompression.h like this" struct ImageDescription { long CodecType long short short short short long CodecQ CodecQ short short Fixed Fixed long short Str31 short short
idSize; cType; resvdl; resvd2; dataReflndex; version; revi sionLevel ; vendor; temporaI Qual i ty; spatiaIQual ity; width; height; hRes; vRes; dataSize; frameCount; name; depth; clutID;
}~ As you can see, the first five fields of an image description are of the same type as the first five fields of a sample description {at least if you know that CodecType is defined as long). In effect, an image description is a sample description that contains some extra fields to hold information about video media. So, when we call AddMediaSample to add a video media sample, we'll pass it an image description, suitably cast to a sample description. But we're not ready to call AddMediaSample quite yet. First we need to create some video media data, the compressed images that, when decompressed, become the frames of our movie. Let's draw some images and compress them.
Drawing Video Frames Our video media data is going to consist of a series of individual compressed images. We are of course free to use any images we like. For fun, let's make the first image in the series a completely white rectangle, the last image in the series a copy of the QuickTime penguin picture, and the intermediate images a progressively greater blend of the first and last images. Figure 6.9 shows the first and last movie frames, together with three intermediate
170
Chapter6 Doug's 1st Movie
Figure 6.9 Someframes of the final movie file.
frames. (In technical jargon, we're going to create a cross-fade between the first and last images.) Listing 6.2 defines the QTMM_DrawFramefunction, which draws a frame of a specified height and width into a specified offscreen graphics world. QTMM_DrawFramealso takes as a parameter the sample number; it uses that number to determine how much blending of the first and last images to perform. Listing 6.2 Drawing a frame of the movie. static void QTMM_DrawFrame (short theTrackWidth, short theTrackHeight, long theNumSample, GWorl dPtr theGWorl d) Handle char static PicHandle static GWorldPtr static Graphics ImportComponent Rect RGBColor ComponentResul t
myHandl e = NULL; myData [kPICTFi I eHeaderSi ze] ; myPicture = NULL; myGWorld = NULL; mylmporter = NULL; myRect; myColor; myErr = noErr;
MacSetRect(&myRect, O, O, theTrackWidth, theTrackHeight); i f (myPicture == NULL) { myErr = NewGWorld(&myGWorld, kPixeIDepth, &myRect, NULL, NULL, (GWorldFlags)O); i f (myErr ! = noErr) goto bai I ; / / read a picture from our resource f i l e myPicture = GetPicture(kPicturelD) ; i f (myPicture == NULL) goto bai I ;
Adding Media Samples 171
/ / use Munger to prepend a 512-byte header onto the picture data; / / this converts the PICT resource data into in-memory PICT f i l e data myHandle = (Handle)myPicture; Munger(myHandle, O, NULL, O, myData, kPICTFileHeaderSize); / / get a graphics importer for the picture myErr = OpenADefaultComponent(Graphics ImporterComponentType, kQTFileTypePicture, &mylmporter) ; i f (myErr ! = noErr) goto bai I ; / / configure the graphics importer myErr = GraphicslmportSetGWorld(mylmporter, myGWorld, NULL); i f (myErr ! = noErr) goto bai I ; myErr = GraphicslmportSetDataHandle(mylmporter, myHandle) ; i f (myErr I= noErr) goto bai I ; myErr = GraphicslmportSetBoundsRect(mylmporter, &myRect); i f (myErr ! = noErr) goto bai I ; / / draw the picture into the source GWorld myErr = GraphicslmportDraw(mylmporter) ; i f (myErr i= noErr) goto bai I ; / / set the blend amount (0 = f u l l y transparent; Oxffff = f u l l y opaque) myColor.red = (theNumSample- 1) * (Oxffff / kNumVideoFrames- 1); myColor.green-- (theNumSample- 1) * (Oxffff / kNumVideoFrames- 1); myColor.blue = (theNumSample- 1) * (Oxffff / kNumVideoFrames- 1); OpColor(&myCol or) ; / / blend the pi cture (in the source GWorld) into the empty rectangle / / (in the dest ination GWorld) CopyBi ts ( (Bi tMapPtr)*GetGWorl dPi xMap(myGWorld), (BitMa pPtr) *GetGWorl dPi xMap(t heGWorld), &myRect, &myRect, blend, NULL);
'1172 Chapter 6 Doug's 1st Movie
if
(theNumSample == kNumVideoFrames)
goto bai I ;
return; bail 9 i f (myHandle != NULL) Di sposeHandl e (myHandle) ; i f (myPicture != NULL) Rel easeResource ( (Handl e)myPi cture) ; i f (mylmporter l: NULL) Cl oseComponent(mylmporter) ;
I won't say much more about QTMM_DrawFrame, because it's not directly concerned with building QuickTime movie files. Basically, it reads an image from a 'PICT' resource, attaches a graphics importer to that image, draws that image into an offscreen graphics world, and then blends that image with the all-white image in the offscreen graphics world passed to QTMM_DrawFrame. You can work through the function if you like, or you can just trust me that, when passed values from 1 to kNumVideoFrames, it generates a series of images that includes the five shown in Figure 6.9.
Compressing Video Frames Now that we've got an image that we want to include as a media sample of our QuickTime movie file, we need to compress it so that it takes up less space on disk. If we didn't do any compression on the video frames, each 152-by-202-pixel frame would occupy about 122,000 bytes, so our entire lO0-frame movie file would occupy about 12 Mbytes. That's a bit large for a l O-second movie. By compressing the movie frames, we can reduce the size of the final movie file to around 470 Kbytes (using ]PEG compression) with no appreciable loss of image quality. The only downside to compressing the movie frames [aside from any image degradation introduced by the image compressor) is that it takes time to compress the frames while building the movie file and it also takes time to decompress the frames during movie playback. But decompressing compressed video media samples is almost always faster than reading larger chunks of uncompressed data from a storage device, and it's orders of magnitude faster than receiving larger chunks of data across a network connection. So compression not only reduces the amount of storage required by a
Adding Media Samples '1173
movie file, it also enhances playback performance by shifting much of the work from the storage device or network connection to the CPU. QuickTime provides a rich set of services for compressing and decompressing images and sequences of images, principally provided by the Image Compression Manager (or, more briefly, the ICM). Right now we are concerned only with compressing our images into video media samples, and we can handle this by using only two ICM functions, GetMaxCompressionSize and Compresslmage. GetMaxCompressionSize tells us the maximum size of our compressed image, given parameters that specify the size of the image to be
compressed, the compressor, and the desired level of compression. We will use that maximum size when allocating a data buffer, into which compress Image will write the compressed image. As a bonus, CompressImage also returns to us an image description whose fields have been set to the correct values for the image it has compressed. As we've seen, we'll need that image description when we eventually call AddMediaSample. The first thing we need to do, before we can draw or compress our image, is create a new offscreen graphics world, which will hold the image drawn by OTMM_DrawFrame. So OTMM_AddVideoSamplesToMedia begins with these lines of code" MacSetRect(&myRect, O, O, theTrackWidth, theTrackHeight); myErr = NewGWorld(&myGWorld, kPixeIDepth, &myRect, NULL, NULL, (GWorl dFl ags)O) ; i f (myErr l= noErr) goto bai I ; myPixMap = GetGWorldPi xMap(myGWorld) ; i f (myPixMap == NULL) goto bai I ; LockPi xel s (myPixMap) ;
There is nothing fancy here; we just set the rectangle myRect to the width and height of the movie frame and call NewGWorld to create an offscreen graphics world of that size. Then we retrieve the pixel map associated with that graphics world and lock the pixel map. Both GetMaxCompressionSize and compress Image operate directly on pixel maps, not on offscreen graphics worlds. Now we can call GetMaxCompressionSize, like this: myErr = GetMaxCompressionSi ze (myPixMap, &myRect, O, / / let ICM choose depth
174
Chapter 6 Doug's 1st Movie
codecNormal Qual i ty, myCodecType, (CompressorComponent) anyCodec, &myMaxComprSi ze) ;
As you can see, we pass GetMaxCompressionSi ze the pixel map, the image rectangle, an image bit depth, a compression quality specifier, the desired compression type, a codec specifier, and a pointer to a long integer. GetMaxCompressionSize will update that long integer with the maximum number of bytes required to hold an image having the specified characteristics compressed using the specified compressor. Once we know the maximum size a compressed image will occupy, we can allocate a buffer to hold the compressed image data, by calling NewHandle: myComprDataHdl = NewHandle (myMaxComprSize) ; i f (myComprDataHdl == NULL) goto bai I ; HLockHi (myComprDataHdl) ; myComprDataPtr = *myComprDataHdl ;
Notice that we lock the handle and then dereference it to obtain a pointer to the data buffer. That's because Compress Image wants us to pass it a pointer, not a handle. We are almost ready to call Compress Image. We need only one more thing, namely, a handle to an image description. As I mentioned earlier, compress Image will fill in the fields of the image description we pass it; it will also resize the image description as necessary, so we'll just pass it a handle to a four-byte block of memory: myImageDesc = ( ImageDescri pt i onHandl e) NewHandle (4) ;
After we've drawn an image into the offscreen graphics world myGWorld, we can compress that image by calling Compress Image, like this: myErr = Compresslmage(myPixMap, &myRect, codecNormaI Qual i ty, myCodecType, mylmageDesc, myComprDataPtr) ; Compress lmage takes as parameters the pixel map of the offscreen graphics world, a rectangle that specifies the portion of the image to compress, the
Adding Media Samples 175
same compression quality and compressor type that we previously passed to fietMaxCompressionSize, the image description, and the pointer to a buffer. If all goes well, myComprOataPtr will point to the compressed image data and myImageOesc will be resized and updated. The actual size of the data buffer can be found by inspecting the dataSi ze field of the image description.
Adding Video Frames to a Media We can finish this all off with one more step. Finally, we are ready to call AddMediaSample to add the compressed image data to the media as a video media sample: myErr = AddMediaSample(theMedi a, myComprDataHdl, O, / / no offset in data (**my ImageDesc). dataSi ze, kVideoFrameDuration, / / frame duration (SampI eDescri pt i onHandI e) myImageDesc, 1, / / one sample O, / / self-contained samples NULL);
The first two parameters here are the media to which we want to add the sample and the sample data itself. The third parameter specifies the byte offset into the sample data buffer at which AddMediaSample should start reading the sample data; since the entire buffer comprises the sample data, we specify 0 as the byte offset. The fourth parameter indicates the number of bytes to be copied into the movie file. As we just saw, we can use the dataSi ze field of the image description to obtain that size. The fifth parameter specifies the duration, in the media time scale, of the sample being added to the media. We are giving each frame of the movie the same duration, which is specified by the constant kVideoFrameDuration: #define kVi deoFrameDuration
kVi deoTimeScal e/lO
Each frame of the movie has a duration of 1/10th of a second. Since there are 100 frames in the movie, the entire movie will last 10 seconds. The sixth parameter to AddMediaSamp] e is a handle to a sample description. As predicted earlier, we can just cast our image description handle to a sample description handle. The seventh parameter indicates the number of samples contained in the data buffer. The eighth parameter is a set of flags, which we can leave set to the default value of 0. The last parameter is a
17G Chapter6 Doug's 1st Movie
pointer to a time value, in w h i c h AddMediaSample w i l l return the media time
at which the sample was added. We don't care about that information, so we pass NULL. Listing 6.3 gives a complete definition of the QTMM_AddVideoSamp] esToMedi a function, which adds 100 samples to the specified media, thereby creating the movie data for our QuickTime movie file. Listing 6.3 Adding samples to a media. OSErr QTMM_AddVideoSamplesToMedia (Media theMedia, short theTrackWidth, short theTrackHeight) GWorldPtr Pi xMapHandle CodecType long long Handle Ptr ImageDescri pti onHandl e CGrafPtr GDHandl e Rect OSErr
myGWorld = NULL; myPixMap = NULL; myCodecType = kJPEGCodecType; myNumSample; myMaxComprSize = OL; myComprDataHdl = NULL; myComprDataPtr = NULL; myImageDesc = NULL; mySavedPort = NULL; mySavedDevice = NULL; myRect; myErr = noErr;
MacSetRect(&myRect, O, O, theTrackWidth, theTrackHeight); myErr = NewGWorld(&myGWorld, kPixeIDepth, &myRect, NULL, NULL, (GWorldFlags)O); i f (myErr != noErr) goto bai I ; myPixMap = GetGWorldPixMap(myGWorld) ; i f (myPixMap == NULL) goto bai I ; LockPi xel s (myPixMap) ; myErr = GetMaxCompressionSi ze (myPixMap, &myRect, O, / / let ICM choose depth codecNormaIQual i ty, myCodecType, (Compres sorComponent ) anyCodec, &myMaxComprSi ze) ; i f (myErr l= noErr) goto bai I ; myComprDataHdl = NewHandle (myMaxComprSize) ;
Adding Media Samples 177
i f (myComprDataHdl == NULL) goto bai I ; HLockHi (myComprDataHdl) ; myComprDataPtr = *myComprDataHdl ; mylmageDesc = (ImageDescriptionHandle)NewHandle(4) ; i f (mylmageDesc == NULL) goto bail ; GetGWorld(&mySavedPort, &mySavedDevice) ; SetGWorld(myGWorld, NULL); for (myNumSample = 1; myNumSample <= kNumVideoFrames; myNumSample++) { EraseRect (&myRect) ; QTMM_DrawFrame(theTrackWidth, theTrackHeight, myNumSample, myGWorld); myErr = Compresslmage(myPixMap, &myRect, codecNormaI Qual i ty, myCodecType, mylmageDesc, myComprDataPtr) ; i f (myErr != noErr) goto bai I ; myErr = AddMediaSample(theMedia, myComprDataHdl, O, / / no offset in data (**my ImageDesc). dataS i ze, kVideoFrameDuration, / / frame duration (SampI eDescri pt i onHandl e)myImageDesc, 1, / / one sample O, / / self-contained samples NULL); i f (myErr != noErr) goto bail ; bail: SetGWorld(mySavedPort, mySavedDevice) ; i f (myImageDesc ! = NULL) Di sposeHandl e ( (Handl e)mylmageDesc) ;
178
Chapter6 Doug's 1st Movie
i f (myComprDataHdl I= NULL) Di sposeHandl e (myComprDataHdl) ; i f (myGWorld ! = NULL) Di sposeGWorl d (myGWorld) ; return (myErr) ;
Saving a M o v i e We've now seen how to create a single-fork, self-contained QuickTime movie file. If we also want to create a Fast Start or interleaved movie file, we need to take one more step and call F1attenMovieData on the new movie. Our sample application QTMakeMovie does not take this extra step, but the application framework that QTMakeMovie is built upon does provide a way for us to do this. We simply need to open the new movie file and select the Save As m e n u item in the File menu. This will result in our application executing the QTFrame_SaveAsMovieFile function, which will prompt us for a new filename and location and then call FlattenMovieData to create a Fast Start, interleaved movie file. The call to F1attenMovieData looks like this: myNewMovie = Fl attenMovi eData ( myMovi e, flattenAddMovieToDataFork I flattenForceMovieResourceBeforeMovieData, &myFile, sigMoviePl ayer, smSystemScri pt, createMovieFi leDeleteCurFi le I createMovieFi leDontCreateResFi le) ;
By default, FlattenMovieData interleaves the movie data, so there is no need to do anything special to get an interleaved movie file. (Of course, since the movie we built in this chapter has only one type of media data, it's already interleaved.) We get a Fast Start movie file by specifying the constant flattenForceMovieResourceBeforeMovieData in the second parameter.
T h e Code The code folder accompanying this chapter contains the project files, source code, and resource data of the sample application QTMakeMovie, for both Macintosh and Windows. QTMakeMovie is just like our basic QTShell application, except that the Test m e n u contains a single m e n u
TheCode
179
Figure 6.10
A movie window in Mac OS X.
item, Create New Movie. When the user selects that item, Q_TMakeMovie calls the QTMM_CreateVideoMovie function (defined in Listing 6.1) to create the "appearing-penguin" movie file. In addition to showing how to create O_uickTime movie files, this code takes yet another important step forward. To wit, this code is completely Carbonized, so that the compiled application runs both under the "classic" Macintosh operating systems that support Carbon (namely, Mac OS 8 and 9) and under Mac OS X. Figure 6.10 shows a frame of the movie created by Q_TMakeMovie when opened by the application running under Mac OS X. As you can see, our movie window automatically uses the stylish new Aqua interface provided by OS X. The code changes made in QTMakeMovie to support Carbon are not very great, since I've been gradually moving toward Carbon-compliant APIs in previous versions of the application framework. The biggest changes concerned the project files for the Macintosh version of the application. As you can see in Figure 6.11, all the Macintosh-specific libraries have been replaced by the single stub library CarbonLib. (The downside here is that QTMakeMovie will not run on "classic" Macintosh operating systems that do not have the CarbonLib system extension installed.)
180
Chapter 6 Doug's 1st Movie
Figure 6.11
The project window for the Carbonized QTMakeMovie.
Conclusion In this chapter, we've made some key advances in our undersanding of QuickTime. We've gotten a taste for the basic structure of QuickTime movie files, and--more important--we've learned how to create QuickTime movie files using the high-level APIs provided by the Movie Toolbox. We'll use the same sequence of functions repeatedly throughout this book whenever we build movie files, whether they contain video, sprite, text, timecode, or other kinds of media data.
Conclusion
181
This Page Intentionally Left Blank
The Informant
Getting and Setting Movie Information
Introduction In the previous chapter, we saw how to create a QuickTime movie file that contains a single video track. We also learned a fair bit about the structure of QuickTime movies (as collections of tracks) and QuickTime movie files [as collections of atoms). In this chapter, we'll continue with the general topic of creating and configuring QuickTime movie files. We'll see how to get various pieces of information about QuickTime movies and movie files; we'll also see how to add information to a QuickTime movie to help the user determine what's in a movie. To get an idea of what we're going to accomplish here, let's suppose that we're running some version of the MoviePlayer application (the predecessor to the current QuickTime Player application). MoviePlayer's Movie menu contains the item Show Copyright. If we select that item immediately after having opened the movie file we created in the previous chapter, we'll see the movie information dialog box shown in Figure 7.1. As you can see, this is not particularly helpful. The only real "information" visible to the user is the first frame of the movie, which happens to be a solid white rectangle. It would be better to display some other frame of the movie and to add some descriptive information to the other panes of the dialog box. Figure 7.2 shows a much more useful movie information dialog box. Part of our task here will be to see how to modify the movie file so that selecting Show Copyright displays the dialog box in Figure 7.2 rather than the one in Figure 7.1. In a nutshell, this involves setting the movie poster to some frame other than the first frame, which is the default poster frame; it also involves attaching three new pieces of movie user data to the movie file. Along the way, we'll also learn how to set the preview that is contained in the file-opening dialog boxes displayed by calls to the StandardGetFi l ePreview and NavGetFi l e functions. Figure 7.3 shows a typical file-opening dialog box with a preview.
183
Figure 7.1
The movie information dialog box for our new movie.
Figure 7.2 The revised movie information dialog box for our new movie.
184
Chapter 7 The Informant
Figure 7.3
A preview contained in a file-opening dialog box.
Our sample application this time around is called QTInfo. As usual, it's based directly on the QTShell sample application that we've developed previously. QTInfo is just QTShell with one additional source code file (OTInfo.c) and some additional resources. Figure 7.4 shows the Test m e n u supported by QTInfo. As you can see, QTInfo provides the Show Copyright m e n u item, as well as a n u m b e r of other items that allow us to get and set various kinds of movie information. It turns out that we can handle the Show Copyright item with a single line of code: ShowMovielnformation(myMovie, gModalFilterUPP, OL);
Figure 7.4
The Test menu in QTInfo.
Introduction
1185
Figure 7.5 A nonmovable movie information dialog box.
The ShowMovielnformation function was introduced in QuickTime version 2.0, but has (to my knowledge) never been documented. ShowMovieInformation simply displays the movie information dialog box, which includes the movie poster image, the name of the movie, the movie's copyright information, and some other information. If you pass a universal procedure pointer to a modal dialog event filter function in the second parameter, you'll get a movable modal dialog box; otherwise, you'll get a standard nonmovable modal dialog box, as shown in Figure 7.5.
Movie Posters A movie poster image (or, more briefly, a movie poster) is a single image that represents a QuickTime movie. The images in the top-left panes of Figures 7.1, 7.2, and 7.5 are movie posters, suitably resized to fit into the available space in the movie information dialog box. A movie poster is defined by specifying a movie poster time and one or more movie poster tracks. The movie poster time specifies the time in the movie at which the image is to be found, and the movie poster tracks specify which tracks in the movie are to be used to create the movie poster. Typically a single track is used as the movie poster track, but in theory, two or more video tracks (or other tracks with visible data) could contribute to the final movie poster image. If a
186
Chapter7 The Informant
movie has no track designated as a movie poster track, then the movie won't have a poster, whatever the setting of the movie poster time. Let's see how to work with poster times and tracks.
Getting and Setting Movie Poster Times The default movie poster time is 0, which picks out the first frame in the movie. As we saw earlier, it's sometimes useful to designate some other time as the movie poster time. The function QXInfo_SetPosterToFrame, defined in Listing 7.1, sets the currently displayed movie frame to be the movie poster image. (QTInfo calls OXInfo_SetPosterXoFrame in response to the Set Poster Frame menu item.) Listing 7.1
Setting the movie poster time to the current movie time.
OSErr QTInfo SetPosterToFrame (Movie theMovie, MovieController theMC)
(
TimeValue ComponentResult
myTime; myErr = noErr;
/ / stop the movie from playing myErr = MCDoAction(theMC, mcActionPlay, (void *)OL); i f (myErr i= noErr) goto bai I ; myTime = GetMovieTime(theMovie, NULL); SetMoviePosterTime(theMovie, myTime); myErr = MCMovieChanged(theMC, theMovie) ; bail: return((OSErr)myErr) ;
}
As you can see, QTlnfo_SetPosterToFrame first calls MCDoAction to set the
movie play rate to O, which stops the movie from playing. {If the movie is already stopped, this call has no effect.} Then OTInfo_SetPosterXoFrame retrieves the current movie time by calling the fietMovieTime function and sets the movie poster time to the current movie time by calling the SetMovi ePosterTime function. QTInfo_SetPosterToFrame finishes up by calling the MCMovieChanged function, which informs the movie controller that we've made changes to the movie using the Movie Toolbox. As we've seen in past chapters, there
Movie Posters 187
are often two ways to change some characteristic of a movie: using Movie Toolbox functions and using movie controller functions. W h e n a movie is associated with a movie controller and w h e n we make a change to the movie using the Movie Toolbox, it's often necessary to keep things in sync by calling MCMovieChanged. For example, if we change the size of the movie by calling SetMovieBox, w e ' d need to call MCMovieChanged so that the movie controller can update itself appropriately. In the present case, there is no movie controller action to set the poster frame, so we used the Movie Toolbox function SetMoviePosterTime. T h e n we called MCMovieChanged on the offhand chance that the movie controller might actually care about the poster time. I've tried running QTInfo without the call to MCMovieChanged here and no h a r m appears to result, but it's better to be safe than sorry. As a general rule, if you have a movie controller associated with a movie and you use the Movie Toolbox to effect some change in the movie, call MCMovieChanged to inform the movie controller of the change. QTInfo supports the Go To Poster Frame m e n u item, which sets the current movie time to the movie poster time. Listing 7.2 defines the QTInfo_GoToPosterFrame function, which does just that.
Listing 7.2 Setting the current movie time to the movie poster time. OSErr QTInfo GoToPosterFrame (Movie theMovie, MovieController theMC)
{
TimeRecord ComponentResult
myTimeRecord; myErr = noErr;
/ / stop the movie from playing myErr = MCDoAction(theMC, mcActionPlay, (void *)OL) ; i f (myErr I= noErr) goto bai I ; / / set up a time record with the desired movie time, scale, and base myTimeRecord.value.hi = O; myTimeRecord, val ue. lo = GetMoviePosterTime(theMovie) ; myTimeRecord.base = GetMovieTimeBase(theMovie) ; myTimeRecord.scale = GetMovieTimeScale(theMovie) ; myErr = MCDoAction(theMC, mcActionGoToTime, &myTimeRecord); bai I 9 return((OSErr)myErr) ;
}
In this case, there is a movie controller action that we can use to set the current movie time, namely, mcActionGoToTime. As a result, there is no need
188
Chapter 7 The Informant
to call MCMovieChanged after we've made this change to the movie [since we made the change using movie controller actions, not the Movie Toolbox). We did of course use Movie Toolbox functions to get information needed to fill in the TimeRecord structure whose address we pass to MCDoAction, but those functions didn't make any changes to the movie; they simply gave us information about the movie.
W o r k i n g w i t h M o v i e Poster Tracks I mentioned earlier that a movie's poster image is determined both by the movie poster time and by the movie poster tracks. Each track in a movie has a track usage, which indicates w h e t h e r the track is used in the movie, the movie poster, the movie preview, or any combination of these. For instance, a movie can include a video track that consists of a single frame, and that track can be the only one in the movie that is used in the movie poster. In this way, it's possible to have a movie poster that is not simply one of the frames in the movie, but is some other image altogether. We can query a track's usage by calling the 6etTrackUsage function. GetTrackUsage returns a long integer whose bits encode the track usage. Currently, these three bits are defined: enum { t rac kUsageI nMovi e t rac kUsageI nPrevi ew trackUsagel nPoster
};
=1<<1, = 1<<2,
=1<<3
By default, a track can be used in any of these three ways, so calling GetTrackUsage on most tracks will return a value of Ox0OOOOOOE (that is, binary 1110). But we can change this default setting by calling SetTrackUsage, passing it a long integer that has the appropriate flags set or clear. We'll see some calls to GetTrackUsage and SetTrackUsage in a moment. For now, it's important to understand that a track usage value indicates a track's potential use, not its actual use. That is to say, if a particular track has a track usage value with the trackUsageInPoster flag set, the poster image might not actually include any data from that track. This might happen if the movie poster time is set to a time at which that track has no data [perhaps the track offset is greater than the movie poster time). Similarly, a track's usage value can have the trackUsagelnPreview flag set, even if the movie has no preview. To repeat, the track usage determines the uses a track can have, not the uses it actually has. Let's see how this works in practice. W h e n QTInfo wants to adjust the state of its menus, it needs to know w h e t h e r the movie in the frontmost window has a poster image. If there is no poster image, then it should disable
Movie Posters 189
the Go To Poster Frame menu item. To determine whether a movie has a poster image, QTInfo calls the QTInfo_MovieHasPoster function defined in Listing 7.3. Essentially, QTInfo_MovieHasPoster looks at each track in the movie, retrieves the track's usage value, and checks to see whether the trackUsageInPoster flag is set in that value. If there is at least one track that is capable of contributing data to the movie poster image, we'll happily count the movie as having a poster image.
Listing 7.3 Determining whether a movie has a poster image. Boolean QTInfo MovieHasPoster (Movie theMovie) long long Track long Boolean
myCount = OL; mylndex = OL; myTrack = NULL; myUsage = OL; myHasPoster = true;
/ / make sure that some track is used in the movie poster myCount = GetMovieTrackCount(theMovie) ; for (mylndex = I; mylndex <= myCount; mylndex++) ( myTrack = GetMovielndTrack(theMovie, mylndex) ; i f (myTrack == NULL) continue; myUsage = GetTrackUsage(myTrack) ; i f (myUsage & trackUsagelnPoster) break;
if
(mylndex > myCount) myHasPoster = false;
return (myHasPoster) ;
The QTInfo MovieHasPoster function is instructive for other reasons as well, in particular because it shows how to iterate through all tracks in a movie. As you can see, it begins by calling the GetMovieTrackCount function to determine how many tracks the specified movie contains. Then it repeatedly calls the GetMovieIndTrack function to get a track identifier for each of those tracks. The Movie Toolbox also supplies the GetMovieIndTrackType function, which allows us to iterate through all tracks of a specific type (say, all video tracks). We won't have occasion to use GetMovieIndTrackType in this chapter, but we will in the future.
190
Chapter 7 The Informant
Movie Previews A movie preview is a short, dynamic representation of a QuickTime movie. Typically, a movie preview is an excerpt of the movie itself (for example, the first few seconds of the movie). But, like a movie poster, a movie preview can consist of data that is not used in the normal playback of the movie. Once again, the usage values of the tracks in the movie determine the actual contents of the movie preview.
Defining Movie Previews We specify a movie preview by giving its start time, its duration, and its tracks. The recommended duration is about 3 to 5 seconds, but we are free to use a longer or shorter duration if we wish. An easy way to let the user specify a movie preview is to provide the Set Preview to Selection m e n u item, which uses the start time and duration of the current movie selection as the start time and duration of the movie preview. Listing 7.4 shows how to set the movie preview to the current movie selection.
Listing 7.4 Setting the movie preview to the current movie selection. OSErr QTlnfo_SetPreviewToSelection (Movie theMovie, MovieController theMC)
{
TimeValue TimeVal ue ComponentResult
myStart; myDurati on; myErr = noErr;
GetMovieSelection(theMovie, &myStart, &myDuration); SetMoviePreviewTime(theMovie, myStart, myDuration); myErr = MCMovieChanged(theMC, theMovie) ; return((OSErr)myErr) ;
The QTlnfo_SetPreviewToSelection function is simplicity itself. We just call GetMovieSelection to get the current movie start time and duration, and then we pass those same values to the SetMoviePreviewTime function. We need to call MCMovieChanged here because we changed the characteristics of the movie (in particular, its movie preview} using the Movie Toolbox. As we've seen, QTInfo also provides the Set Selection to Preview menu item, which sets the movie's selection to the current movie preview. Listing 7.5 defines the function QTInfo_SetSelectionToPreview, which performs this operation.
Movie Previews 191
Listing 7.5 Setting the current movie selection to the movie preview. OSErr QTInfo_SetSelectionToPreview (Movie theMovie, MovieController theMC)
{
TimeValue TimeVal ue ComponentResult
myStart; myDurat i on; myErr = noErr;
GetMoviePreviewTime(theMovie, &myStart, &myDuration); SetMovieSelection(theMovie, myStart, myDuration); myErr = MCMovieChanged(theMC, theMovie); return((OSErr)myErr) ;
We need to enable or disable the Set Preview to tion to Preview m e n u items, depending on w h e t h e r or preview. It's easy to determine w h e t h e r a movie simply call GetMovieSelection and check to see returned to us is greater than O, like this:
Selection and Set Seleca movie has a selection has a selection: we can w h e t h e r the duration
GetMovieSelection(myMovie, &myStart, &myDuration); myHasSelection = (myDuration > 0);
But it's a bit more complicated to determine w h e t h e r a movie has a movie preview. We need to check to see both w h e t h e r the movie has a nonzero movie preview duration and w h e t h e r any tracks in the movie are used in the movie preview. Listing 7.6 defines the QTInfo_MovieflasVreview function, which performs both of these checks. QTInfo_MovieHasVreview is very similar to OTInfo_MovieHasPoster (see Listing 7.3).
Listing 7.6 Determining whether a movie has a preview. Boolean QTInfo MovieHasPreview (Movie theMovie) m
TimeVal ue TimeVaI ue long long Track l ong Boolean
192
Chapter 7 The Informant
myStart; myDurat i on; myCount : OL; mylndex = OL; myTrack = NULL; myUsage = OL; myHasPreview = false;
/ / see i f the movie has a positive preview duration GetMoviePreviewTime(theMovie, &myStart, &myDuration) ; i f (myDuration > O) myHasPrevi ew = true; / / make sure that some track is used in the movie preview myCount = GetMovieTrackCount(theMovie) ; for (mylndex = 1; mylndex <= myCount; mylndex++) { myTrack = GetMovielndTrack(theMovie, mylndex) ; i f (myTrack == NULL) continue; myUsage = GetTrackUsage(myTrack) ; i f (myUsage & trackUsageInPreview) break; i f (myIndex > myCount) myHasPreview = false; return (myHasPrevi ew) ;
Playing Movie Previews The Movie Toolbox provides an easy way to show the user the exact contents of a movie preview. We can call the PlayMoviePreview function, like this: PlayMoviePreview(myMovie, NULL, OL);
When we execute PlayMoviePreview, the Movie Toolbox puts our movie into preview mode, plays the movie preview in the movie's graphics port, and then sets the movie back into normal playback mode. When the movie returns to normal playback mode, the current movie time is set to the end of the movie preview. The second parameter to PlayMoviePreview is a universal procedure pointer to a movie callout function, which the Movie Toolbox calls repeatedly while the preview is playing. We might use a movie callout function to provide a way for the user to stop the preview from playing (perhaps by checking the event queue for some particular key press). If we don't use a movie
Movie Previews 193
callout function, then the call to PlayMoviePreview is essentially synchronous: no other events will be processed until the movie preview finishes playing. The Movie Toolbox provides a way to play a movie preview without blocking other processing. We can call SetMoviePreviewMode with its second parameter set to true to put a particular movie into preview mode. 5etMoviePreviewMode restricts the active segment of the movie to the segment of the movie picked out by the preview's start time and duration; it also restricts the active tracks to those that have the trackUsageInPreview flag set in their track usage values. Once a movie has been set into preview mode, we can start it and stop it by calling the 5tartMovie and StopMovie functions. To exit movie preview mode, we can call SetMoviePreviewMode with its second parameter set to fa] se. (Note that QTInfo does not illustrate this method of playing movie previews; it calls P] ayMovieVrevi ew.I
Clearing Movie Previews Sometimes it's useful to clear a movie preview from a movie. We can do this by setting both the start time and duration of the movie preview to 0, like this"
SetMoviePreviewTime(theMovie, O, 0); Executing this line alone effectively prevents any movie preview from being displayed. But we also want to perform a few other actions. For one thing, we should remove any tracks from the movie that are used only in the movie preview. We can do this by examining the track usage value for each track in the movie and, if the usage value indicates that a track is used in the movie preview but not in the movie or the movie poster, calling Dispose~ MovieTrack to remove the track from the movie. Also, once we've removed any tracks that were used only in the movie preview, we should go back through the remaining tracks and reset their track usage values so that they can be used as part of a movie preview, if one is subsequently added. If we don't do this, the user might be unable to create a new movie preview, since it's possible that none of the remaining tracks in the movie has the trackUsageInPreview flag set in its track usage value. Listing 7.7 defines the QTInfo_ClearPreview function, which performs all three of these actions.
194
Chapter 7 The Informant
Listing 7.7 Clearing a movie preview. OSErr QTInfo ClearPreview (Movie theMovie, MovieController theMC) n
1ong long Track long ComponentResult
myCount mylndex myTrack myUsage myErr =
= OL; = OL; = NULL; = OL; noErr;
/ / set the movie preview start time and duration to 0 SetMoviePreviewTime(theMovie, O, 0); / / remove all tracks that are used *only* in the movie preview myCount = GetMovieTrackCount(theMovie) ; for (mylndex = myCount; mylndex >= 1; mylndex--) { myTrack = GetMovielndTrack(theMovie, mylndex) ; i f (myTrack == NULL) continue; myUsage = GetTrackUsage(myTrack) ; myUsage &= trackUsagelnMovie I trackUsagelnPreview I trackUsagelnPoster; i f (myUsage == trackUsagelnPreview) Di sposeMovieTrack (myTrack) ; / / add trackUsagelnPreview to any remaining tracks that are in the movie / / (so that subsequently setting the preview to a selection w i l l include / / these tracks) myCount = GetMovieTrackCount (theMovi e) ; for (mylndex = 1; mylndex <= myCount; mylndex++) { myTrack = GetMovielndTrack(theMovie, mylndex) ; i f (myTrack == NULL) continue; myUsage = GetTrackUsage(myTrack) ; i f (myUsage & trackUsagelnMovie) SetTrackUsage (myTrack, myUsage I trackUsagelnPrevi ew) ; myErr = MCMovieChanged(theMC, theMovie) ; return((OSErr)myErr) ;
Movie Previews 195
File P r e v i e w s Now consider this question: w h e n we call StandardGetFilePreview (or NavGetFile with the preview pane enabled), what is displayed in the preview section of the file-opening dialog box? Before you answer, take a look back at Figure 7.3. I suspect you're inclined to say that it's the movie preview. But before you make that your final answer, take a look at Figure 7.6, which shows another file-opening dialog box. And then take a look at Figure 7.7, which shows yet another file-opening dialog box. Thoroughly confused? I thought so.
196
Figure 7.6
A poster contained in a file-opening dialog box.
Figure 7.7
A description contained in a file-opening dialog box.
Chapter 7 The Informant
The correct a n s w e r to our little quiz is that the p r e v i e w displayed in a fileopening dialog box is w h a t ' s called a file preview, w h i c h is any information that gives the user an idea of w h a t ' s in the file. As w e ' v e seen, the file preview can be a movie poster or a movie p r e v i e w (if the file is a movie file)or any other data that describes or represents the file. On M a c i n t o s h computers, the default file p r e v i e w for a Q u i c k T i m e movie file is a m i n i a t u r e version of the movie poster frame, while on W i n d o w s c o m p u t e r s it's the first 10 seconds of the movie. But we are free to specify some other information as the file preview, if we so desire. Let's see h o w file p r e v i e w s are stored and created, to m a k e this all p e r h a p s a bit clearer.
Accessing File Previews On Macintosh computers, w h e n StandardGetFilePreview or NavGetFile needs to display a file p r e v i e w for a Q u i c k T i m e movie file, it first checks to see w h e t h e r the file is a double-fork or single-fork movie file. If the selected file is a double-fork movie file, StandardGetFi lePreview or NavGetFi le looks in the resource fork for a resource of type 'pnot'. The data in a 'pnot' resource is organized as a preview resource record, w h i c h is defined in ImageCompress i on. h like this: struct PreviewResourceRecord { unsigned long short OSType short
};
modDate; version; resType; resID;
The resType and resID fields specify the type and ID of some other resource, w h i c h contains the actual file p r e v i e w data or w h i c h itself indicates w h e r e to find that data. {Let's call that other resource the preview data resource.) For instance, if resType and resID pick out a resource of type 'PICT', then the picture in that resource will be used as the file preview [as in Figure 7.3). Similarly, if resType and resID pick out a resource of type 'TEXT', then the text in that resource will be used as the file preview [as in Figure 7.7). If resType and resID pick out a resource of type 'moor', then the movie preview start time and duration specified in that resource will be used to pick out the file preview [as in Figure 7.6). If there is no movie resource in the resource fork, then resID should be set to -1 (OxFFFF), w h i c h tells StandardGetFilePreview to use the movie previe w w h o s e start time and duration are stored in the movie atom in the file's data fork. In single-fork movie files, there is no resource fork. So StandardGetFi l ePreview opens the data fork and looks for an a t o m of type 'pnot', w h i c h it interprets in the same w a y as a 'pnot' resource, w i t h one small difference:
File Previews
197
the resID field is interpreted as a 1-based index of atom types in the movie file. For example, if the resIype field in the 'pnot' atom in a single-fork movie file is 'PICI' and the resID field is 1, then StandardGetFilePreview looks for the first atom in that file of type 'PICI', which it then uses as the file preview. There are a couple of "gotchas" here of which you should be aware. First, the NavGetFile function currently seems to work only with file previews specified by 'pnot' resources. If you're creating single-fork movie files (as I have recommended), don't expect them to have file previews in the fileopening dialog boxes displayed by NavGetFi l e. Worse yet, NavGetFile doesn't seem to know how to handle movie previews as file previews, even in double-fork movie files. Finally, StandardGetFilePreview doesn't seem to know how to handle movie previews as file previews w h e n stored in singlefork movies. (At least, I haven't been able to get them to work.) Our strategy in the following will be to create single-fork movie files with 'pnot' atoms in the format that is publicly documented. Then we'll just have to wait until StandardGetFilePreview and NavGetFile catch up to us (as I expect they will). You might be wondering (by the wayl w h y file preview resources and atoms have the type 'pnot'. The 'p' of course is for "preview"; but what's the 'not' all about? The constant assigned to the component that displays file previews is of no help in deciphering this: enum { ShowFilePreviewComponentType = FOURCHARCODE('pnot')
};
I'm told, by a knowledgeable source, that early development builds of the QuickTime software--prior to version 1.0--contained a preview component that wasn't very good. When the replacement was written, it was given the type 'pnot' as an abbreviation for "Preview? Not!"
Creating File Previews Ideally, we'd like the QuickTime movie files that we create to have file previews so that the user can get a reasonable idea of what's in those files w h e n they appear in the list of files in a file-opening dialog box. The Image Compression Manager provides the MakeFilePreview function, which we can use to create file previews. Apple documentation recommends calling MakeFilePreview whenever we save a movie file. So we can insert a call to MakeFilePreview in the two functions OTFrameUpdateMovieFile and QTFrame_SaveAsMovieFile (both in the file ComFramework.c) that handle the Save and Save As menu commands: m
198
Chapter7 The Informant
MakeFi I ePrevi ew(myRefNum, (I CMProgressProcRecordPtr) - 1) ; MakeFilePrevi ew sets the file preview for the file specified by the myRefNum parameter to be the current movie preview, if one exists; if the movie does not have a movie preview, then MakeFi ]ePreview creates a thumbnail version of the movie poster image and sets it to be the file preview. (A t h u m b n a i l is a small copy of an image, typically 80 pixels on the longer side.) If we want to create a file preview using some other type of data (for instance, text datal, we can call the ICM function AddFi l ePreview, which allows us to specify the type of data we want to use. But there is one big problem here: MakeFilePreview and AddFilePreview always add the file preview information to the movie file's resource fork. Indeed, MakeFilePreview and AddFilePreview will go so far as to create a resource fork for the movie file if it doesn't already have one so that they have a place to put the file preview they create. Needless to say, this behavior is going to w r e a k havoc with our desire to create only single-fork movie files. So, however tempting it might be to use MakeFilePreview to create our file previews, we're just going to have to resist that temptation. In short, QuickTime does not currently provide any API to add a file preview to a single-fork movie file. But based on w h a t we have learned about the way file previews are stored in single-fork files and, in the previous chapter, about the general structure of QuickTime movie files, it w o n ' t be too hard for us to do this ourselves. For, we know that a single-fork movie file is just a collection of atoms. And a file preview can be stored in a singlefork movie as an atom of type 'pnot' together with a preview data atom that holds the actual preview data. So all we really need to do is append an atom or two to a single-fork movie file. Figure 7.8 shows a single-fork movie file with no file preview (a) and that same file with a file preview (b). We'll
Y moor
Movie atom data
x mdat
Movie data
(a)
Y moov
Movie atom data
x mdat
Movie data
20 pnot
Preview resource record
z
PICT
Preview data
Figure 7.8 A single-fork movie file before and after adding a file preview.
File Previews
199
define a function QTInfo_MakeFilePreview that we can use to turn the top file into the bottom file. The function QTInfo MakeFilePreview is declared like this: m
OSErr QTInfo_MakeFilePreview (Movie theMovie, short theRefNum, ICMProgressProcRecordPtr theProgressProc) As you can see, QTInfo MakeFilePreview has the same parameters as MakeFilePreview, except that we also pass the movie identifier to QTInfo_MakeFilePreview. The second parameter to QTInfo_MakeFilePreview is the file reference number of the open movie file. If QTInfo_MakeFi lePreview is passed a reference to a resource fork, then it can just call MakeFilePreview to add the r e q u i r e d p r e v i e w resources to that resource fork, like this: m
i f (QTInfo_IsRefNumOfResourceFork(theRefNum)) { myErr = MakeFilePreview(theRefNum, theProgressProc) ; goto bai I ;
}
But if QTInfo_MakeFilePreview is passed the file reference number of a data fork, then we'll a s s u m e that w e m u s t add the file p r e v i e w i n f o r m a t i o n to the data fork. This involves adding a 'pnot' a t o m to the data fork, as well as a p r e v i e w data atom. Recall that an a t o m consists of an a t o m h e a d e r a n d some a t o m data. For a 'pnot' atom, the a t o m data is a record of type Previ ewResourceRecord. So we can construct the 'pnot' a t o m v e r y easily. First declare the local variables we need: Previ ewResourceRecord unsigned long
myPNOTRecord; myAtomHeader[2] ;
/ / an atom header
T h e n fill in the a t o m header: myAtomHeader[0] EndianU32 NtoB(sizeof(myAtomHeader) + sizeof(myPNOTRecord)) ; myAtomHeader[1] = EndianU32 NtoB(ShowFilePreviewComponentType);
Then fill in the a t o m data: GetDateTime(&myModDate) ; myPNOTRecord.modDate = EndianU32 NtoB(myModDate); myPNOTRecord.version = EndianS16 NtoB(O) ; myPNOTRecord.resType = EndianU32 NtoB(myPreviewType) ; myPNOTRecord.resID = EndianS16 NtoB(1) ; D
200
Chapter7 The Informant
All data in predefined QuickTime movie atoms must be in big-endian format, so here we use the macros EndianU32 NtoB and EndianS16 NtoB to convert from the computer's native-endian format into big-endian format. Notice that the resType field is set to myPreviewType. We'll create a file preview that is either a movie preview or a movie poster thumbnail, depending on w h e t h e r the movie has a movie preview: . .
m
i f (QTInfo MovieHasPreview(theMovie)) myPrevi ewType = MovieAID; else myPreviewType = kQTFileTypePicture;
The next thing we need to do is write the 'pnot' atom data onto the end of the movie file. We can use the File Manager functions GetEOF, SetEOF, SetFPos, and FSWrite to do this. Listing 7.8 (which we'll consider shortly) shows the exact steps involved in writing the data into the file. Now we need to write the actual preview data into an atom of the appropriate type. For a movie preview, we can just point to the 'moov' atom, w h i c h contains the start time and duration of the movie preview. For a file preview that contains a thumbnail of the movie poster frame, we need to retrieve the movie poster frame, create a thumbnail image from it, and write the atom onto the end of the movie file. We can call GetMoviePosterPict to get the movie poster image" myPicture = GetMoviePosterPict (theMovie) ; Then we can call the ICM function MakeThumbnaiIFromPicture to reduce the
poster image to a thumbnail image: myThumbnail = (PicHandle)NewHandleClear(4); myErr = MakeThumbnaiI FromPicture(myPi cture, O, myThumbnail , theProgressProc) ; If MakeThumbnail FromPi cture successfully creates the thumbnail image, we need to 611 in an atom header and write the header and thumbnail data into the movie file as an atom of type 'PICT', like this: myAtomHeader[O] = EndianU32 NtoB(sizeof(myAtomHeader) + GetHandl eSi ze ( (Handl e) myThumbnai I ) ) ; myAtomHeader[1] = EndianU32 NtoB(myPreviewType) ; D
/ / write the atom header into the f i l e mySize : sizeof(myAtomHeader) ; myErr = FSWrite(theRefNum, &mySize, myAtomHeader);
File Previews
2.,01
i f (myErr -= noErr) { / / write the atom data into the f i l e mySize = GetHandleSize((Handl e)myThumbnai I ) ; myErr = FSWrite(theRefNum, &mySize, *myThumbnail) ;
}
Listing 7.8 brings all of this together into a single function that writes the appropriate file preview into the resource fork or the data fork, depending on the kind of file reference number passed to it in the second parameter. Listing 7.8 Creating a file preview. OSErr QTInfo MakeFilePreview (Movie theMovie, short theRefNum, ICMProgressProcRecordPtr theProgressProc) unsigned long Previ ewResourceRecord long long unsigned long OSType OSErr
myModDate; myPNOTRecord; myEOF; mySi ze; myAtomHeader[2] ; myPrevi ewType; myErr = noErr;
/ / an atom header
i f (QTInfo IsRefNumOfResourceFork(theRefNum)) { myErr = MakeFilePreview(theRefNum, theProgressProc) ; goto bai I ;
}
/ / i f the movie has a movie preview, use that as the f i l e preview; otherwise use / / a thumbnail of the movie poster frame as the f i l e preview i f (QTInfo_MovieHasPreview(theMovie)) myPrevi ewType = MovieAID; else myPreviewType = kQTFileTypePicture; / / construct the 'pnot' atom; f i l l in the 'pnot' atom header myAtomHeader[O] = EndianU32 NtoB(sizeof(myAtomHeader) + sizeof(myPNOTRecord)) ; myAtomHeader[1] = EndianU32 NtoB(ShowFilePreviewComponentType) ; // fill
in the 'pnot' atom data
GetDateTime (&myModDate) ; myPNOTRecord.modDate = EndianU32 NtoB(myModDate); myPNOTRecord.version = EndianS16 NtoB(O); myPNOTRecord,resType = EndianU32 NtoB(myPreviewType) ; myPNOTRecord.resID = EndianS16 NtoB(1); m
m
202
Chapter 7 The Informant
/ / write the 'pnot' atom at the end of the data fork / / get the current logical e n d - o f - f i l e and extend i t by the desired amount myErr = GetEOF(theRefNum, &myEOF); i f (myErr ! = noErr) goto bai I ; myErr = SetEOF(theRefNum, myEOF + sizeof(myAtomHeader) + sizeof(myPNOTRecord)); i f (myErr ! = noErr) goto bai I ; / / set the f i l e mark myErr = SetFPos(theRefNum, fsFromStart, myEOF); i f (myErr ! = noErr) goto bai I ; / / write the atom header into the f i l e mySize = sizeof(myAtomHeader) ; myErr = FSWrite(theRefNum, &mySize, myAtomHeader); i f (myErr ! = noErr) goto bai I ; / / write the atom data into the f i l e mySize = sizeof(myPNOTRecord) ; myErr = FSWrite(theRefNum, &mySize, &myPNOTRecord); i f (myErr ! = noErr) goto bai I ; / / write the preview data atom at the end of the data fork i f (myPreviewType == MovieAID) { / / the 'pnot' atom refers to the existing 'moov' atom / / so no other preview data atom is required
}
i f (myPreviewType == kQTFileTypePicture) { PicHandle myPicture = NULL; PicHandle myThumbnail = NULL; / / get the poster frame picture myPicture = GetMoviePosterPict (theMovie) ; i f (myPicture ! = NULL) { / / create a thumbnail myThumbnail = (PicHandle)NewHandleClear(4) ; i f (myThumbnail != NULL) { myErr = MakeThumbnaiI FromPicture(myPicture, O, myThumbnail, theProgressProc) ;
File Previews 203
i f (myErr -= noErr) { myAtomHeader[O] = EndianU32_NtoB(sizeof(myAtomHeader) + GetHandl eSi ze ( (Handl e) myThumbnai I ) ) ; myAtomHeader[1] = EndianU32_NtoB(myPreviewType) ; / / write the atom header into the f i l e mySize = sizeof(myAtomHeader) ; myErr = FSWrite(theRefNum, &mySize, myAtomHeader); i f (myErr == noErr) { / / write the atom data into the f i l e mySize = GetHandleSize((Handl e)myThumbnai I ) ; myErr = FSWrite(theRefNum, &mySize, *myThumbnail);
}
Ki I l Picture (myThumbnai I ) ; Ki I l Picture (myPi cture) ;
bail" return (myErr) ;
}
I should point out that QTInfo_MakeFilePreview is not terribly smart about adding file previews to single-fork files. In particular, QTInfo MakeFilePreview doesn't bother to check whether the movie file already contains a 'pnot' atom. Instead, it simply appends a new 'pnot' atom and its associated preview data atom to the file. One consequence of this is that each time the user changes any aspect of the movie and saves it, a new thumbnail is appended to the movie file; but that thumbnail might never be used, since StandardGetFilePreview will always find the first 'pnot' atom and the first preview data atom. In the next chapter, we'll address this issue and see how to replace an existing 'pnot' atom and its associated preview data atom. w
Movie Annotations A QuickTime movie file can include one or more movie annotations, which provide descriptive information about the movie contained in the file. For example, movie annotations can indicate the names of the performers in the
21~1~ Chapter 7 The Informant
movie, the software that was used to create the movie, the names of the movie's writer and director, general information about the movie, and so forth. The header file Movies.h defines over two dozen kinds of movie annotations. For the present, we'll be concerned with only three of them, picked out by these constants: enum { kUserDataText Ful l Name kUserDataTextCopyri ght kUserDataText I nformat i on
}
= FOUR CHAR CODE(' 9 = FOUR CHAR CODE(' 9 = FOUR CHAR CODE(' 9
These are the three movie annotations that appear in the movie information dialog box displayed by the ShowMovieInformation function {see Figure 7.21. What we want to do now is show how to add these three kinds of movie annotations to a QuickTime movie file; or, if a movie file already contains annotations of these sorts, we w a n t to show how to edit those annotations. We'll handle both of these tasks by displaying an Edit Annotation dialog box that contains an editable text field in which the user can add or edit an annotation. For example, if the user selects Add Information in the Test m e n u of QTInfo but the frontmost movie has no information annotation, we'll display the dialog box shown in Figure 7.9. As you might have guessed from the constants we've listed, a movie annotation is stored in a QuickTime movie file as a piece of movie user data. We've already worked a little with the GetMovieUserData, GetUserDataltem, and SetUserDataItem functions for getting and setting a piece of a movie's
Figure 7.9 QTInfo's Edit Annotation dialog box.
Movie Annotations
205
user data (see Chapter 2, "Control"). Because the data for a movie annotation is always text data, here we'll use the GetUserDataText and AddUserDataText functions, which are specialized versions of GetUserDataItem and SetUserDataItem. W h e n the user selects one of our three m e n u items for adding or editing a movie annotation, QTInfo executes the QTInfo EditAnnotation function, passing it a movie identifier and the type of annotation to add or edit. For instance, if the user selects the Add Information item, QTInfo executes this block of code: m
case IDM ADD INFORMATION. mylsChanged = QTInfo EditAnnotation(myMovie, kUserDataTextlnformation) ; i f (mylsChanged) (**myWindowObject) . f l s D i r t y = true; mylsHandled = true; break; D
In the QTInfo_EditAnnotation function, we need to display the Edit Annotation dialog box, put the current movie annotation of the selected kind (if one exists) into the editable text field, allow the user to alter the annotation as desired, and then--if the user clicks the OK button--retrieve the new or edited annotation and attach it to the movie file as a piece of movie user data. Let's consider each of these steps.
Creating the Edit Annotation Dialog Box Our Edit Annotation dialog box contains four items, as shown in the ResEdit version of our dialog item list ('DITL') resource depicted in Figure 7.10. To be honest, I must admit that I simply "borrowed" this item list from the resource fork of the QuickTime Player application (and I was even too lazy to r e n u m b e r it). To refer to the items in this dialog box, we'll define these constants: #define #define #define #define #define
kEditTextResourceID kEdi tTextltemOK kEdi tTextltemCancel kEditTextltemEdi tBox kEdi tText ItemEdi tLabel
548 1
2 3 4
Our resource fork also contains a 'DLOG' resource of the same ID (again "borrowed" from QuickTime Player) that uses this dialog item list. We can open the Edit Annotation dialog box, therefore, by executing this code: myDialog : GetNewDialog(kEditTextResourcelD, NULL, (WindowPtr)-iL) ;
206
Chapter7 The Informant
Figure 7.10 The dialog item list for the Edit Annotation dialog box.
The dialog box is initially invisible, so that we have an opportunity to configure it before displaying it on the screen. For instance, we want to set both the default button {which is outlined in bold and activated w h e n the user types the Return or Enter key) and the Cancel button {which is activated w h e n the user types the Escape key or the Command-Period key combination). We can do this as follows: SetDialogDefaultltem(myDialog, kEditTextltemOK) ; SetDialogCancel Item(myDialog, kEditTextltemCancel) ;
Next, we want to set the static text movie annotation is being added or 'STR#' that contains three strings, one tion that QTInfo can handle. We'll strings: #define #define #define #define
kTextKi ndsResourceID kTextKindsFul IName kTextKi ndsCopyri ght kTextKi nds Informati on
item {item 4) to indicate which type of edited. I've added a resource of type for each of the types of movie annotause these constants to access those
2000 1
2 3
We'll simply retrieve one of these strings from that resource, according to the type of annotation that QTInfo_EditAnnotation is asked to handle, as shown in Listing 7.9.
Movie Annotations
207
Listing 7.9 Setting the label for a movie annotation. / / get a string for the specified annotation type switch (theType) { case kUserDataTextFul IName: GetlndString(myString, kTextKindsResourceID, kTextKindsFulIName) ; break; case kUserDataTextCopyright: GetlndString(myString, kTextKindsResourceID, kTextKindsCopyright); break; case kUserDataTextI nformati on: GetIndString(myString, kTextKindsResourceID, kTextKindslnformation); break; GetDialogltem(myDialog, kEditTextltemEditLabel, &myltemKind, &myltemHandle, &myltemRect); SetDialogItemText(myltemHandle, myString) ;
As you can see, we call GetDialogltem to get a handle to the static text item and SetDialogItemText to set the string as the text of that item.
Showing the Current Annotation We also want to call SetDialogltemText to set the current annotation, if one exists, as the text of the editable text item. First, however, we need to find the current annotation of the specified type. As m e n t i o n e d earlier, we'll use the GetUserDataText function to do this. GetUserDataText reads the movie annotation of a specified type from a user data item list, w h i c h we first obtain by calling GetMovieUserData, like this: myUserData = GetMovieUserData (theMovi e) ; GetUserDataText returns the requested information in a handle, w h i c h it resizes as necessary to exactly hold the text. So we can retrieve the current movie annotation of the desired type using code like this: myHandle = NewHandleClear(4) ; i f (myHandle I= NULL) { myErr = GetUserDataText(myUserData, myHandle, theType, 1, GetScri ptManagerVari abI e ( smRegi onCode)) ; / / some I ines omitted here
}
208
Chapter 7 The Informant
The final parameter passed to GetUserDataText is a region code, which specifies a version of a written language of a particular region in the world. It's possible to have several movie annotations of the same type, which differ only in their region code--that is to say, their language. Here we're using the Script Manager function GetScriptManagerVariable to get the region code associated with the user's current script system. Once we've called GetUserDataText to get the current annotation of the specified type, we need to copy the text in myHandle into a Pascal string. That's because SetDialogItemText takes a Pascal string as a parameter, not a handle. We can use the function QTInfo TextHandleToPString, defined in Listing 7.10, to make this conversion.
Listing
7.10
Copying text from a handle into a Pascal string.
void QTInfo_TextHandleToPString (Handle theHandle, Str255 theString)
{
short
myCount;
myCount = GetHandleSize(theHandle) ; i f (myCount > 255) myCount = 255; theStri ng[O] = myCount; BlockMoveData(*theHandle, &(theString[1]), myCount) ;
So now we are finally ready to insert the existing annotation into the Edit Annotation dialog box. We can do this with these two lines of code" GetDialogltem(myDialog, kEditTextltemEditBox, &myltemKind, &myltemHandl e, &myltemRect) ; SetDialogltemText (myltemHandle, myString) ;
The final thing we need to do before displaying the dialog box to the user is set the current selection range of the annotation text. When QuickTime Player displays its Edit Annotation dialog box, it selects all the text in the editable text item. We'll follow this example by calling Sel ectDi al ogI temText like this: SelectDialogltemText(myDialog, kEditTextltemEditBox, O, myString[O]) ;
At this point, the Edit Annotation dialog box is fully configured. Its static text item has been updated to indicate which type of movie annotation is being edited, and the current annotation of that type has been inserted into the editable text item. We can finish up by actually showing the dialog box to the user: Movie Annotations
209
MacShowWindow(GetDi al ogWindow(myDi al og) ) ;
Retrieving the Edited Annotation We allow the user to interact with the items in the Edit Annotation dialog box by calling Modal Di a 1og" do { ModaIDialog(gModal Fi IterUPP, &myltem) ; } while ((myItem != kEditTextltemOK) && (myltem ! = kEditTextltemCancel));
As you can see, Modal Dial og is called continually until the user clicks the OK or Cancel button (or types a key or key combination that is i n t e r p r e t e d as a click on one of those buttons). If t h e user clicks the Cancel button, we should just exit the QTInfo_EditAnnotation function after disposing of the Edit Annotation dialog box and p e r f o r m i n g any other necessary cleanup. i f (myltem ! = kEditTextltemOK) goto bai I ;
But if the user clicks the OK button, we need to retrieve the text in the editable text item and set it as the movie annotation of the specified type. We can get the edited text like this" GetDi aIog Item (myDi aI og, kEdit Text I temEdi tBox, &myI temKi nd, &myI temHandl e, &myI temRect) ; GetDialogltemText(myltemHandle, myString) ;
We want to call AddUserDataText to insert the user's edited annotation into the movie user data list. To do this, we first need to convert the Pascal string returned by GetDialogItemText into a handle. We can use the QTInfo_PStringToTextHandl e function, defined in Listing 7.11, to handle this conversion.
Listing 7.11 Copying text from
a Pascal string into a handle.
void QTInfo_PStringToTextHandle (Str255 theString, Handle theHandle)
{
SetHandleSize(theHandle, theString[O]) ; i f (GetHandleSize(theHandle) ! = theString[O]) return; BlockMoveData(&(theString[1]), *theHandle, theString[O]) ;
210
Chapter 7 Thelnformant
Now we are ready to call AddUserDataText" myErr = AddUserDataText(myUserData, myHandle, theType, 1, GetScri ptManagerVari abI e ( smRegionCode) ) ;
Again, we're calling GetScriptManagerVariable to get the user's current region code so that the annotation is written into the movie file in a form recognizable to the user. Listing 7.12 shows the complete function QTInfo_ Edi tAnnotati on.
Listing
7.12
Editing a movie annotation.
Boolean QTInfo_EditAnnotation (Movie theMovie, OSType theType) DialogPtr short short GrafPtr Handle short Handle UserData Rect Str255 Boolean OSErr
myDialog = NULL; myltem; mySavedResFi I e; mySavedPort; myHandle = NULL; myltemKi nd; myltemHandl e; myUserData= NULL; myltemRect; myString; mylsChanged = false; myErr = noErr;
/ / save the current resource f i l e and graphics port mySavedResFi le = CurResFile() ; Get Port (&mySavedPort) ; / / set the application's resource f i l e UseResFi I e (gAppResFi le) ; / / get the movie user data myUserData = GetMovieUserData (theMovi e) ; i f (myUserData == NULL) goto bai I ; / / create the dialog box in which the user will add or edit the annotation myDialog = GetNewDialog(kEditTextResourceID, NULL, (WindowPtr)-lL) ; i f (myDialog == NULL) goto bai I ;
Movie Annotations 211
# i f TARGET API MAC CARBON SetPortDi al ogPort (myDial og) ; #else MacSetPort (myDial og) ; #endif SetDialogDefaultltem(myDialog, kEditTextltemOK) ; SetDialogCancel Item(myDialog, kEditTextItemCancel) ; / / get a string for the specified annotation type switch (theType) { case kUserDataTextFul IName" GetIndString(myString, kTextKindsResourceID, kTextKindsFulIName) ; break; case kUserDataTextCopyri ght 9 GetlndString(myString, kTextKindsResourceID, kTextKindsCopyright); break; case kUserDataTextInformati on 9 GetlndString(myString, kTextKindsResourceID, kTextKindslnformation); break; GetDialogltem(myDialog, kEditTextltemEditLabel, &myltemKind, &myltemHandle, &myltemRect); SetDialogltemText(myltemHandle, myString) ; / / set the current annotation of the specified type, i f i t exists myHandle = NewHandleClear(4) ; i f (myHandle ! = NULL) { myErr = GetUserDataText(myUserData, myHandle, theType, 1, GetScri ptManagerVari able (smRegi onCode)) ; i f (myErr == noErr) { QTInfo_TextHandleToPString(myHandle, myString) ; GetDi al ogltem(myDi al og, kEditText ItemEdi tBox, &myltemKind, &myltemHandle, &myltemRect); SetDialogltemText(myltemHandle, myString) ; SelectDialogltemText(myDialog, kEditTextltemEditBox, O, myString[Ol) ; Di sposeHandl e (myHandle) ; MacShowWindow(GetDi al ogWindow(myDial og) ) ;
212
Chapter7 Thelnformant
/ / display and handle events in the dialog box until the user clicks OK or Cancel do { ModaIDialog(gModal Fi IterUPP, &myltem) ; } while ((myltem ! = kEditTextltemOK) && (myltem ! = kEditTextltemCancel)); / / handle the selected button i f (myItem ! = kEditTextltemOK) goto bai I ; / / retrieve the edited text myHandle = NewHandleClear(4) ; i f (myHandle ! = NULL) { GetDi al ogltem(myDi al og, kEditText ItemEdi tBox, &myltemKind, &myltemHandle, &myltemRect); GetDi al ogl temText (myI temHandl e, myStri ng); QTInfo_PStringToTextHandle(myString, myHandle) ; myErr = AddUserDataText(myUserData, myHandle, theType, 1, GetScri ptManagerVari abI e ( smRegionCode) ) ; mylsChanged = (myErr == noErr) ; Di sposeHandl e (myHandle) ; bail 9 / / restore the previous resource f i l e and graphics port MacSetPort (mySavedPort) ; UseResFi I e (mySavedResFi I e) ; i f (myDialog ! = NULL) Di sposeDi al og (myDial og) ; return (myI sChanged) ;
Note that QTlnfo EditAnnotation returns a Boolean value that indicates whether the user clicked the OK button and the specified movie annotation was successfully updated. QTInfo uses that value to determine w h e t h e r it should mark the movie as dirty [and hence in need of saving). It's possible, however, that the user clicked the OK button without having altered the movie annotation in the editable text item. In that case, the movie would be marked as dirty even though its user data had not actually changed. It would be easy to modify QTInfo EditAnnotation so that it compares the original annotation and the annotation later retrieved from the text box to see whether they differ. This enhancement is left as an exercise for the reader. u
Movie Annotations 213
(It's worth noting, however, that the behavior of QTInfo in this regard is identical to that of QuickTime Player.)
Conclusion In this chapter, we've learned how to get and set some of the information that's stored in a QuickTime movie file. We've seen how to work with movie posters and movie previews, and we've seen how to add file previews to both double-fork and single-fork QuickTime movie files. We still have a little bit of work to do on the QTlnfo_MakeFilePreviewfunction (which we've deferred until the following chapter), but already it can write file previews into single-fork movie files. We've also seen how to add annotations to a movie file and edit a file's existing annotations. Our sample application QTInfo allows the user to edit any of the three kinds of annotations displayed in the movie information dialog box. With just a little bit of work, however, the QTInfo_EditAnnotation function could be modified to support editing any type of movie annotation. So what we've got are the essential elements of a general-purpose tool for adding and changing any text-based movie user data. But, as I've said, we still have some work to do to clean up one or two loose ends in this chapter's code. In the next chapter, we'll see how to find specific atoms in a QuickTime movie file. We'll also discover another kind of atom structure that can be found lurking deep inside QuickTime movie files.
214
Chapter7 The Informant
The Atomic Caf6
Working with Atoms and Atom Containers
Introduction In the past two chapters, we've been concerned at least in part with atoms, the basic building blocks of QuickTime movie files. Atoms are utterly simple in structure (a 4-byte length field, followed by a 4-byte type field, followed by some data), and this utter simplicity means that atoms can be used for a very wide range of tasks. Indeed, the atom-based structure used by QuickTime movie files is so general and so flexible that it has been adopted by the International Standards Organization (ISO) as the basis for the development of a unified digital media storage format for the MPEG-4 specification. In this chapter, we're going to continue investigating the basic structure of QuickTime files as sequences of atoms. You might recall that in the previous chapter, we left some unfinished business lying around. Namely, we need to see how to replace an existing atom of a particular type instead of just adding a new atom of that type. It turns out that handling this task in the general case is reasonably difficult, since we can't safely move the movie data atom around in a movie file without doing a lot of work. For the present, we'll be content to see how to amend the OTlnfo_MakeFilePreview function we developed last time so that there is at most one 'pnot' atom in a QuickTime movie file. Because an atom can contain any kind of data whatsoever, it can contain data that consists of one or more other atoms. So, atoms can be arranged hierarchically. We'll take a few m o m e n t s to consider the hierarchical arrangement of a movie atom (the main repository of bookkeeping information in a QuickTime movie file). Then we'll show how to put our atomfusing powers to work to create a shortcut movie file, which is a QuickTime movie file that does nothing more than point to some other QuickTime movie file. Once we've played with atoms for a while, we're going to shift gears rather abruptly to consider a second kind of atom-based structure, which
215
we'll call an atom container. Atom containers are structures of type QTAtomContai ner that are often used inside of QuickTime movie data atoms to store various kinds of information (for example, media samples). They were developed primarily to address some of the shortcomings of atoms. In particular, the Movie Toolbox provides an extensive API for working with atom containers; among other things, this API makes it easy to create and access data arranged hierarchically within atom containers. We'll get some hands-on experience with atom containers in two ways. First, we'll see how to get and set the user's Internet connection speed preference, which is a piece of information that QuickTime stores internally and happily gives, in the form of an atom container, to anyone w h o asks. Second, we'll see how to add a movie track to a QuickTime movie. By using movie tracks, we can embed entire QuickTime movies inside of other QuickTime movies. The movie media handler, which manages movie tracks, is one of the most exciting new features in QuickTime 4.1. Once we understand h o w to work with atom containers, it'll be easy to add movie tracks to an existing QuickTime movie. Before we begin, though, a word about terminology. As you've been warned, this chapter is going to discuss two different ways of organizing data, both of which are (for better or worse) called "atoms." The first kind of atom is the one that's used to define the basic structure of QuickTime movie files. The second kind of atom is the one that was introduced in QuickTime 2.1 for storing data in some kinds of media samples (and for other tasks as well); these kinds of atoms are structures of type QTAtom that are stored inside of an atom container. Some of Apple's QuickTime documentation refers to the first kind of atom as a classic atom (perhaps in the same spirit that one refers to a classic car: it's been around a while) and to the second kind of atom as a Q T atom (drawing of course on the data type QTAtom). Some other documentation refers to the first kind of atom as a chunk atom (perhaps because it's just a chunk of data?). I'm not particularly happy with any of these terms, so I'm going to refer to the first kind of atom simply as an atom and to the second kind as an atom container atom. In other words, an atom container atom (of type QTAtom) is always found inside of an atom container (of type QTAtomContainer). Generally, here and in the future, the context will make it clear which kind of atom we're considering, so we can usually get by just talking about atoms.
File Previews: The Sequel In the previous chapter, we saw how to add a 'pnot' atom to a QuickTime movie file, to create a single-fork movie file with a file preview. (A file preview is the movieclip, image, text, or other data that appears in the preview
216
Chapter8 The Atomic Caf~
pane of the file-opening dialog box displayed by a call to StandardGetFilePreview or NavGetFi ]e.) Our strategy was simple: each time the user saves a movie, add a preview atom and [if necessary] a preview data atom to the QuickTime movie file. But we recognized that ultimately we would need to refine this strategy to avoid ending up with multiple preview atoms and preview data atoms. It's time to make some changes to our QTInfo application. In this section, we'll see how to upgrade QTInfo into a nearly identical application, called QTInfoPlus, that handles file preview atoms better.
Removing Existing Previews In fact, we can solve this little problem by adding a single line of code to the OTInfo MakeFi]ePreview function. Immediately after determining that the file reference number passed to OTInfo_MakeFi lePreview picks out a data file, we can execute this code" n
QTInfo RemoveAll PreviewsFromFi le(theRefNum) ; The QTInfo_RemoveAlIPreviewsFromFile function looks through the specified
open data file and removes any existing preview atoms (that is, atoms of type 'pnot') from that file. In addition, this function removes any preview data atoms referenced by those preview atoms, unless the preview data atoms are of type 'moor'. {We don't want to remove atoms of type 'moov', of course, since they contain essential information about the movie.)QTInfo_RemoveAl 1PreviewsFromFile is defined in Listing 8.1.
Listing 8.1 Removing all preview atoms from a QuickTime movie file. OSErr QTInfo RemoveAll PreviewsFromFile (short theRefNum)
{
long short short OSErr
myAtomType = OL; myAtomlndex = O; myCount = O; myErr = noErr;
/ / count the preview atoms in the f i l e myCount = QTInfo_CountAtomsOfTypelnFile(theRefNum, OL, ShowFilePreviewComponentType) ; while (myCount > O) { / / get the preview data atom targeted by this preview atom myAtomType = ShowFiI ePrevi ewComponentType; myAtomlndex = myCount; myErr = QTInfo FindPreviewAtomTarget(theRefNum, &myAtomType, &myAtomlndex) ; / / i f the preview data atom is the last atom in the f i l e , remove i t / / (unless i t ' s a 'moov' atom)
File Previews: The Sequel 2.17
i f (myErr == noErr) i f (myAtomType != MovieAID) i f (QTInfo IsLastAtomlnFile(theRefNum, myAtomType, myAtomlndex)) QTInfo_RemoveAtomFromFile(theRefNum, myAtomType, myAtomlndex); m
/ / remove or free the preview atom i f (QTInfo IsLastAtomlnFile(theRefNum, ShowFilePreviewComponentType, myCount)) QTInfo_RemoveAtomFromFi I e (theRefNum, ShowFiI ePrevi ewComponentType, myCount); else QTI n fo_FreeAtomInFi I e (theRefNum, ShowFi I ePrevi ewComponentType, myCount); / / i f the preview data atom s t i l l exists, remove or free i t i f (myErr == noErr) i f (myAtomType l= MovieAID) i f (QTInfo IsLastAtomlnFile(theRefNum, myAtomType, myAtomlndex)) QTInfo RemoveAtomFromFile(theRefNum, myAtomType, myAtomlndex); else QTInfo FreeAtomInFile(theRefNum, myAtomType, myAtomlndex); myCount--; return (myErr) ;
As you can see, QTlnfo_RemoveAl 1PreviewsFromFi le calls a handful of other functions defined by our application. These other functions do things like count the number of existing preview atoms, find the preview data atom that is the target of a preview atom, determine whether a given atom is the last atom in the file, and so forth. OTlnfo_RemoveAl 1PreviewsFromFi le puts these functions to work like this: for each preview atom in the file (starting with the one nearest the end of the file), find the preview data atom that is referenced by the preview atom. If that target atom isn't a movie atom and it's the last atom in the file, remove it from the file. Then, if the preview atom is the last atom in the file, remove it as well. If the preview atom isn't the last atom in the file, then change it into a free a t o m (that is, an atom whose type is FreeAtomType). By changing the atom type, we're converting the preview atom into a block of unused space at its current location in the movie file. QuickTime simply ignores any atoms of type FreeAtomType that it encounters w h e n reading through a movie file. You might think that we could just remove a preview atom from the file and, if it isn't the last atom in the file, move any following atoms up in the
218
Chapter8 The Atomic Caf~
file. This would avoid creating "islands" of unused space in our file, but it would be a dangerous thing to do. That's because some atoms in a QuickTime file reference data in other atoms by storing offsets from the beginning of the file. In general, we want to avoid moving atoms around in a QuickTime movie file. It's safer just to convert any u n w a n t e d atoms that are not at the end of the file into free atoms. Once we've removed a preview atom (if it's the last atom in the file} or converted it into a free atom (if it isn't), we then look once again to see if the preview data atom is the last item in the file. This might happen if the preview data atom originally preceded the preview atom and the preview atom was the last atom in the file. If the preview data atom is now the last atom in the file, it's removed; otherwise, it's converted into a free atom. The net result of all this is to remove any existing preview and preview data atoms from the file, either by truncating the file to exclude those atoms or by converting them into free atoms. At this point, OTInfo_MakeFilePreview can safely add a new preview atom and (if necessary) a preview data atom to that file. So, w h e n all is said and done, the QuickTime movie file will end up with exactly one preview atom and one preview data atom. In the next few subsections, we'll consider how to define the various QTInfoPlus functions called by QTInfo_RemoveAl l Previ ewsFromFi I e.
Finding and Counting Atoms The most fundamental thing we need to be able to do, w h e n working with a file that's composed of atoms, is find an atom of a specific type and index in that file. For instance, we might need to find the first movie atom, or the third preview atom, or the third 'PICT' atom in the file. So we want to devise a function that takes an atom type and an index and then returns to us the position in the file at which that atom begins, if there is an atom of that type and index in the file. Otherwise, the function should return some error. This task is reasonably straightforward. All we need to do is start at the beginning of the file (or at some other offset in the file specified by the caller) and inspect the type of the atom at that location. If the desired index is 1 and the desired atom type is the type of that atom, we're done" we've found the desired atom. Otherwise, we need to keep looking. We can find the next atom in the file by moving forward in the file by the size of the atom currently under consideration. We continue inspecting each atom and moving forward in the file until we find the atom of the specified type and index or until we reach the end of the file. Listing 8.2 defines the function QTInfo_FindAtomOfTypeAndlndexlnFi le, which is our basic atom-finding tool.
File Previews: The Sequel 2119
Listing 8.2
Finding an atom in a QuickTime movie file.
OSErr QTInfo_FindAtomOfTypeAndlndexlnFile (short theRefNum, long *theOffset, long theAtomType, short thelndex, long *theDataSize, Ptr *theDataPtr) short l ong long long long OSType Ptr Boolean OSErr
mylndex = 1; myFi I eSi ze; myFi I ePos = OL; myAtomHeaderr2]; mySize = OL; myType = OL; myDataPtr = NULL; isAtomFound= false; myErr = paramErr;
i f (theOffset == NULL) goto bai I ; i f (QTInfo IsRefNumOfResourceFork(theRefNum)) goto bai I ; m
myFilePos = *theOffset; / / get the total size of the f i l e GetEOF(theRefNum, &myFileSize) ; while (!isAtomFound) { myErr = SetFPos(theRefNum, fsFromStart, myFilePos) ; i f (myErr ! = noErr) goto bai I ; / / read the atom header at the current f i l e position mySize = sizeof(myAtomHeader) ; myErr = FSRead(theRefNum, &mySize, myAtomHeader); i f (myErr i= noErr) goto bai I ; mySize = EndianU32 BtoN(myAtomHeader[O]); myType = EndianU32 BtoN(myAtomHeader[1]); i f ((mylndex =: thelndex) && ((theAtomType : : myType) II (theAtomType : : kQTlnfoAnyAtomType))) {
220
Chapter 8 The Atomic Cafe
/ / we found an atom of the specified type and index; / / return the atom i f the c a l l e r wants i t i f (theDataPtr ! = NULL) { myDataPtr = NewPtrClear(mySize) ; i f (myDataPtr == NULL) { myErr = MemError() ; goto bai I ;
}
/ / back up to the beginning of the atom myErr = SetFPos(theRefNum, fsFromStart, myFilePos) ; i f (myErr ! = noErr) goto bai I ; myErr = FSRead(theRefNum, &mySize, myDataPtr) ; i f (myErr ! = noErr) goto bai I ;
i sAtomFound = true; } else { / / we haven't found an atom of the specified type and index; keep on looking myFi I ePos += mySize; i f ((theAtomType == myType) II (theAtomType == kQTInfoAnyAtomType)) myIndex++; / / make sure we're moving forward in the f i l e , but not too f a r . . . i f ((mySize <= O) II (myFilePos > (myFileSize - sizeof(myAtomHeader)))) {
} }
}
myErr = cannotFindAtomErr; goto bai I ;
/ / while (!isAtomFound)
/ / i f we got to here, we found the correct atom i f (theOffset l= NULL) *theOffset = myFilePos; i f (theDataPtr ! = NULL) *theDataPtr = myDataPtr; i f (theDataSize l= NULL) *theDataSize = mySize; bail: i f (myErr l : noErr)
File Previews: The Sequel 221
i f (myDataPtr != NULL) Di sposePtr(myDataPtr) ; return (myErr) ;
QTInfo FindAtomOfTypeAndlndexlnFile returns to its caller the offset within the fl]e of the beginning os the atom of the desired type and index. In addition, if the caller passes in non-NULL values in the theDataPtr or theDataSize parameters, QTInfo_FindAtomOfTypeAndlndexInFile returns a copy os the entire atom (including the atom header) or the atom size to the caller. The returned offset, data, and atom size can be used for a variety of purposes. For instance, Listing 8.3 defines the QTInfoCountAtomsOfTypeInFile function, which counts the number of atoms of a specific type in a file.
Listing 8.3
Counting the atoms in a QuickTime movie file.
short QTInfo_CountAtomsOfTypelnFile (short theRefNum, long theOffset, long theAtomType)
(
short long long OSErr
mylndex = O; myFilePos = theOffset; myAtomSize = OL; myErr = noErr;
i f (QTInfo IsRefNumOfResourceFork(theRefNum)) return (mylndex) ; while (myErr == noErr) { myErr = QTInfo FindAtomOfTypeAndlndexlnFile(theRefNum, &myFilePos, theAtomType, 1, &myAtomSize, NULL); i f (myErr == noErr) mylndex++; myFilePos += myAtomSize; m
/ / avoid an infinite loop... i f (myAtomSize <= O) break; return (mylndex) ;
222.
Chapter 8 The Atomic Caf~
QTInfo_CountAtomsOfTypelnFi l e uses the offset and atom size returned by QTInfo_FindAtomOfTypeAndIndexInFile to walk through the file looking for atoms of the specified type. Similarly, it's easy to use QTInfo_FindAtomOfTypeAndIndexInFile to determine whether a particular atom is the last atom in a file. We simply call QTInfo_FindAtomOfTypeAndIndexInFile to get the offset in the file of the given atom and then call it again to see if there are any atoms of any kind following that atom. Listing 8.4 defines a function that does precisely this. Listing 8.4
Determining whether an atom is the last atom in a file.
Boolean QTInfo IsLastAtomlnFile (short theRefNum, long theAtomType, short thelndex)
{
Boolean long long OSErr
isLastAtom = false; myOffset = OL; myAtomSize = OL; myErr = noErr;
/ / find the offset and size of the atom of the specified type and index in the f i l e myErr = QTInfo FindAtomOfTypeAndlndexlnFile(theRefNum, &myOffset, theAtomType, thelndex, &myAtomSize, NULL); i f (myErr == noErr) { / / look for an atom of any type following that atom myOffset += myAtomSize; myErr = QTInfo FindAtomOfTypeAndIndexlnFile(theRefNum, &myOffset, kQTInfoAnyAtomType, 1, NULL, NULL); i f (myErr ! = noErr) isLastAtom = true; m
return(i sLastAtom) ;
Finding the P r e v i e w Data A t o m Given a preview atom, we sometimes need to know which other atom is the target of that atom. In other words, we want to find the atom that we've been calling the preview data atom--the atom that contains the data for the file preview. This is fairly easy" we just need to read the data in the preview atom, which has the structure of a PreviewResourceRecord record. Listing 8.5 defines the QTInfo FindPreviewAtomTarget function, which does this.
File Previews' The Sequel
223
Listing 8.5 Findingthe target of a preview atom. OSErr QTInfo FindPreviewAtomTarget (short theRefNum, long *theAtomType, short *theIndex)
{
long Previ ewResourceRecord long OSErr
myOffset = OL; myPNOTRecord; mySi ze; myErr = noErr;
i f ((theAtomType == NULL) II (thelndex == NULL)) return (paramErr) ; / / find the offset of the atom of the specified type and index in the f i l e myErr = QTInfo_FindAtomOfTypeAndlndexlnFile(theRefNum, &myOffset, *theAtomType, *thelndex, NULL, NULL); i f (myErr == noErr) { / / set the f i l e mark to the beginning of the atom data myErr = SetFPos(theRefNum, fsFromStart, myOffset + (2 * sizeof(long))) ; i f (myErr == noErr) { / / read the atom data mySize = sizeof(myPNOTRecord) ; myErr = FSRead(theRefNum, &mySize, &myPNOTRecord); i f (myErr == noErr) ( *theAtomType = EndianU32 BtoN(myPNOTRecord.resType) ; *thelndex = EndianS16 BtoN(myPNOTRecord.resID) ;
}
,
B
return (myErr) ;
QTlnfo FindPreviewAtomTarget calls QTlnfo FindAtomOfTypeAndlndexlnFile to find the location of the atom whose type and index are passed to it in the theAtomType and theIndex parameters. Then it advances the file mark to the beginning of the atom data and reads the atom data into myPNOTRecord. The type and index of the preview data atom (suitably converted from big-endian to native-endian form) are then returned to the caller. m
Removing and Freeing Atoms It's quite easy to remove an atom from a file or convert it into a free atom. Listing 8.6 shows how we define the QTInfo_RemoveAtomFromFile function, which removes an atom from a file by truncating the file at the beginning of the atom {by calling SetEOF). Note that any atoms that follow the specified
224
Chapter 8 The Atomic Caf~
atom are also r e m o v e d from the file. To avoid any problems, we s h o u l d always call QTInfo IsLastAtomInFile to m a k e sure that the atom to be r e m o v e d from the file is the last atom in the file.
Listing
8.6
Removing an atom from a file.
OSErr QTInfo RemoveAtomFromFile (short theRefNum, long theAtomType, short thelndex)
{
long long OSErr
myOffset -- OL; myAtomSize = OL; myErr = noErr;
/ / find the offset of the atom of the specified type and index in the f i l e myErr = QTInfo FindAtomOfTypeAndlndexlnFile(theRefNum, &myOffset, theAtomType, thelndex, &myAtomSize, NULL); i f (myErr == noErr) myErr = SetEOF(theRefNum, myOffset); return (myErr) ;
It's almost as easy to convert an atom into a free atom. All we need to do is position the file m a r k to the beginning of the type field in the atom h e a d e r and write the value 'free' into that field. Listing 8.7 shows how we do this.
Listing
8.7
Freeing an atom in a file.
OSErr QTInfo FreeAtomlnFile (short theRefNum, long theAtomType, short thelndex)
{
m
OSType long long OSErr
myType = EndianU32 NtoB(FreeAtomType); mySize = sizeof(myType) ; myOffset = OL; myErr = noErr;
/ / find the offset of the atom of the specified type and index in the f i l e myErr = QTInfo FindAtomOfTypeAndlndexlnFile(theRefNum, &myOffset, theAtomType, thelndex, NULL, NULL); i f (myErr =- noErr) { / / change the atom type to 'free' myErr = SetFPos(theRefNum, fsFromStart, myOffset + sizeof(long)); i f (myErr --= noErr) myErr = FSWrite(theRefNum, &mySize, &myType);
}
return (myErr) ;
File Previews: The Sequel
225
So allow from forth.
far, then, w e ' v e m a n a g e d to define a handful of utility functions that us to find atoms in files, get the sizes of those atoms, r e m o v e a t o m s files, count the n u m b e r of atoms of a specific type in a file, and so These are precisely the functions called by the QTInfo_RemoveAllPreviewsFromFile function, w h i c h w e ' r e using to m a k e sure that any QuickTime movie file we create or edit has at most one p r e v i e w resource. It w o u l d be easy (and fun) to define an entire library of a t o m utilities, but we'll have to restrain our p r o g r a m m i n g urges here. We've got other w o r k to do.
S h o r t c u t M o v i e Files I m e n t i o n e d earlier that an atom can contain any kind of data, and in particular it can contain other atoms. That is to say, atoms can be arranged hierarchically. Up to now, w e ' v e w o r k e d w i t h a Q u i c k T i m e movie file only as a m e r e concatenation of atoms. We've looked at the data of several of those atoms, but we h a v e n ' t yet met any atoms that contain other atoms. It's time for that to change. A good example of an atom that contains other atoms is the movie a t o m itself. A typical movie atom contains a track atom (of type TrackAID) for each track in the Q u i c k T i m e movie, along with other atoms that contain the movie metadata. A movie atom can also contain a movie user data atom (of type UserDataAID), w h i c h contains the movie user data. A track atom, in turn, contains other atoms that define the track characteristics and that point to the media data, and so on, as deep as is necessary to completely characterize a movie and its data. An atom that contains no other atoms is called a leaf atom. A leaf a t o m m a y or m a y not actually contain any data. Typically, a leaf atom does contain data, but it's possible that the very p r e s e n c e in the file of the atom has significance. In that case, the leaf atom consists solely of the 8-byte a t o m header. An atom that contains one or more other atoms is called a container atom. A movie atom is a container atom. By contrast, a preview atom is a leaf atom, since it contains data but no other atoms. (A preview atom points to or references another atom, but it does not contain it.) Let's build a container atom. Now, it's beyond our c u r r e n t capabilities to build a typical movie atom, with all its complicated s u b a t o m s and subsubatoms. But there is a kind of Q u i c k T i m e movie file that consists entirely of a movie atom and that is simple enough for us to build; this kind of file is called a shortcut movie file. A shortcut movie file is a movie file that picks out a single other movie file. It's rather like an alias file in the Macintosh file system or a shortcut on Windows. Opening a shortcut movie file using the
226
Chapter8 The Atomic Caf~
Movie Toolbox function 0penNovieFi l e causes QuickTime to look for the file that is referred to by the shortcut movie file; if that target file can be found, then 0penMovieFi ]e opens it and returns to the caller a file reference n u m b e r for that target file. Shortcut movie files provide a cross-platform mechanism for referring to QuickTime movie files. They can be useful in all the same ways that alias files (on Mac) or shortcuts (on Windows) can be useful, at least w h e n working with QuickTime movies. For instance, a Web page might contain an embedded URL to a shortcut movie file. To update the movie displayed in the Web page, the webmaster needs only to create a new shortcut movie file that refers to the updated movie and then put the new shortcut movie file in the location occupied by the previous shortcut movie file. In this way, the contents of the Web page can be changed without altering the actual HTML tags of the page. QuickTime has supported shortcut movie files since version 3.0. QuickTime version 4.0 introduced the Movie Toolbox function CreateShortcutMovieFile, which we can use to create a shortcut movie file. But the structure of shortcut movie files is so simple that we can build them ourselves. A shortcut movie file consists entirely os a single movie atom, which in turn contains a movie data reference alias atom (of type MovieDataRefAliasAID). This atom contains a single data reference atom (of type DataRefAID]. Finally, the data reference atom is a leaf atom that contains the type of the data reference followed immediately by the data reference itself. Figure 8.1 shows the general structure of a shortcut movie file. It's easy enough to create a file that has this structure. The only thing we don't yet know is what a data reference is, and one must be put into the data reference atom. In the next chapter, we'll take a long look at data references; for the moment, we'll just suppose that a suitable data reference is passed to us. (To look ahead a bit, a data reference is a handle to some data that picks out a movie file or other file. For instance, a URL data reference is a handle to the NULL-terminated string of characters in the URL.) Listing 8.8 shows the f u n c t i o n QTShortCut CreateShortcutMovieFile that takes that data reference and data reference type and then builds a shortcut movie file.
x + 16
x +8
x
moov mdra dref Figure
8.1
Data reference atom data
The structure of a shortcut movie file.
Shortcut Movie Files 2 2 7
Listing 8.8 Creating a shortcut movie file. OSErr QTShortCut CreateShortcutMovieFile (Handle theDataRef, OSType theDataRefType, FSSpecPtr theFSSpecPtr) m
{
long OSErr
myVersion = OL; myErr = noErr;
myErr = Gestalt(gestaltQuickTime, &myVersion) ; i f (myErr ! = noErr) goto bai I ; i f (((myVersion >> 16) & Oxffff) >= Ox0400) { / / we're running under QuickTime 4.0 or greater myErr = CreateShortcutMovieFile(theFSSpecPtr, sigMoviePl ayer, smCurrentScri pt, createMovieFi leDeleteCurFi le I createMovieFi leDontCreateResFi le, theDataRef, theDataRefType) ; } else { / / we're running under a version of QuickTime prior to 4.0 OSType myDataRefType; unsigned l o n g myAtomHeaderSi ze; Ptr myData = NULL; Handle myAtom = NULL; / / create the atom data that goes into a data reference atom (we will create this / / atom's header when we create the movie atom that contains i t ) ; the atom data is / / the data reference type followed by the data reference i t s e l f myDataRefType = EndianU32 NtoB(theDataRefType) ; myAtomHeaderSize = 2 * sizeof(long); m
/ / allocate a data block and copy the data reference type and data reference into i t myData = NewPtrClear(sizeof(OSType) + GetHandleSize(theDataRef)) ; i f (myData == NULL) goto bai I ; BlockMove(&myDataRefType, myData, sizeof(OSType)) ; BlockMove(*theDataRef, (Ptr) (myData + sizeof(OSType)), GetHandleSize(theDataRef)) ; / / create a handle to contain the size and type fields of the movie atom, as well as / / the size and type fields of the movie data reference alias atom contained in i t / / and of the data reference atom contained in the movie data reference alias atom myAtom = NewHandleClear(3 * myAtomHeaderSize);
228
Chapter 8 The Atomic Caf~
i f (myAtom == NULL) goto bai I ; / / f i l l in the size and type fields of the three atoms *((long *) (*myAtom + OxO0)) = EndianU32_NtoB((3 * myAtomHeaderSize) + GetPtrSi ze (myData)) ; *((long *) (*myAtom + Ox04)) = EndianU32 NtoB(MovieAID) ; *((long *) (*myAtom + Ox08)) = EndianU32 NtoB((2 * myAtomHeaderSize) + GetPtrSi ze (myData)) ; *((long *) (*myAtom + OxOC)) = EndianU32 NtoB(MovieDataRefAliasAID) ; *((long *) (*myAtom + OxlO)) = EndianU32_NtoB((1 * myAtomHeaderSize) + GetPtrSi ze (myData)) ; *((long *)(*myAtom + 0x14)) = EndianU32 NtoB(DataRefAID); m
/ / concatenate the data in myData onto the end of the movie atom myErr = PtrAndHand(myData, myAtom, GetPtrSize(myData)) ; i f (myErr ! = noErr) goto bai I ; / / create the shortcut movie f i l e myErr = QTShortCut WriteHandleToFile(myAtom, theFSSpecPtr) ; bail: i f (myData ! = NULL) Di sposePtr (myData) ; i f (myAtom!= NULL) Di sposeHandl e (myAtom) ;
return (myErr) ;
Our function QTShortCut CreateShortcutMovieFile calls the Movie Toolbox function CreateShortcutMovieFile if it's available; otherwise, it creates the movie atom itself, by building up three consecutive atom headers and then appending the data reference type and data onto the end of those atom headers. It writes the entire movie atom into the specified file by calling the QTShortCut_WriteHandleToFile function. (We've already encountered a version of this function, called QTDX_WriteHandleToFile; see Chapter 5, "In and Out.")
Atom Containers QuickTime version 2.1 introduced a new way to store information that greatly facilitates creating hierarchical collections of data and retrieving data
Atom Containers 229
from those collections. The basic ideas are very simple: at the root of the data hierarchy is an object called an atom container. Inside of an atom container are other objects, called atoms. (If we need to distinguish these atoms from the ones we've been considering up to now, we'll call them atom container atoms.} An atom can contain other atoms, in which case it is a parent atom. The atoms that are contained within a parent atom are called its child atoms. If an atom contains only data (and no other atoms}, it is a leaf atom. The data in a leaf atom is always in big-endian format. (Well, almost always; we'll encounter an exception to this rule in a little while.} An atom has an atom type and an atom ID. A parent atom can contain any n u m b e r of children of any type and ID. The only restriction is that, for a given parent, no two children can have the same type and ID. So we can uniquely identify an atom by specifying its parent, its type, and its ID. (For an atom that is contained directly in the atom container, the atom container is considered to be the atom's parent; the special constant kParentAtomIsContainer is used to signal this fact.} We can also identify a particular atom by specifying its parent, its type, and an index of atoms of that type in that parent. (QuickTime supports yet a third method of identifying atoms, using the atom's position in the atom container, called its offset; we w o n ' t consider this way of identifying atoms here.} Let's consider a few examples. Figure 8.2 shows a very simple collection of data, where the atom container has just two children, each of which holds a long integer that represents the length (in millimeters} of a lizard. These leaf atoms both have the atom type '1 z] n'. Figure 8.3 shows a more complicated arrangement of data. In this case, the root atom container contains two parent atoms, both of type ']dat' (for "lizard data"}. Within each ']dat' atom are two children, which have different types. The atom of type 'lzln' contains a long integer (as in Figure 8.21, and the atom of type ']nam' (for "lizard name"} contains a string of characters. {This is neither a C string nor a Pascal string; it's just the characters themselves.} Notice that both ']zln' atoms have an atom ID of 1; this is OK, since those atoms have different parents. Atom containers can be vastly more complicated than the ones shown in Figures 8.2 and 8.3, and they don't have to exhibit the kind of nice symmetry we see there. On the other hand, some real-life atom containers are just that simple. But no matter how complicated they are, we'll use the same functions to build atoms and atom containers and to retrieve data from atom containers. Let's see how to accomplish these tasks.
238
Chapter8 The Atomic Caf~
I Atom container I
I
~,o~,ype ~,o~,0 ~,o~,~
I
~l~z~nl ;1~ I ~1~0~1
I
I~z~nl I~ I I~ I
Figure 8.2 A simple atom container.
I Atom container I
I
Idat 1
]Z
In
lz In
In am
]
Avl'il
i0 !9
I
Inam
]
1
12 i3
May
Figure 8.3 A more complex atom container.
Creating
Atom
Containers
The file Movies.h defines these types for w o r k i n g w i t h a t o m s and a t o m containers: typedef typedef typedef typedef
Handle 1ong long long
QTAtomContai ner; QTAtom; QTAtomType; QTAtomID;
Notice that an a t o m container is just a handle to some data (structured in a specific way, to be sure). This m e a n s that we can d e t e r m i n e the size of an a t o m container by using the function GetHandl eSi ze. T h a t ' s about as m u c h as we need to k n o w about the w a y an a t o m container is stored in m e m o r y . The actual structure of an a t o m container is publicly d o c u m e n t e d , but t h a n k f u l l y w e will not need to learn a n y t h i n g about that structure. The Movie Toolbox provides all the functions we'll n e e d in order to create and use a t o m s and a t o m containers.
Atom Containers
231
We create an atom container by calling the QTNewAtomContainer function, like this: QTAtomContainer myAtomContainer= NULL; myErr = QTNewAtomContainer(&myAtomContai ner) ;
If QTNewAtomContainer completes successfully, then the value of the variable myAtomContainer is a new, e m p t y atom container. We can then add atoms to that container by calling QTInsertChild. For instance, to add the two children shown in Figure 8.2 to this atom container, we could execute this code: myLong = EndianU32 NtoB(1029); myErr = QTInsertChild(myAtomContainer, kParentAtomlsContai ner, kLizardLength, 1, O, sizeof(myLong), &myLong, NULL); myLong = EndianU32 NtoB(1253) ; myErr = QTInsertChild(myAtomContainer, kParentAtoml sContai ner, kLizardLength, 2, O, sizeof(myLong), &myLong, NULL);
The second p a r a m e t e r to the QTlnsertChild function specifies the parent atom of the child w e ' r e inserting. Here, you'll notice, w e ' r e using the constant kParentAtomIsContainer to indicate that the parent atom is the atom container itself. The third and fourth parameters specify the type and ID of the new atom. The fifth p a r a m e t e r is the desired index of the new atom within the parent atom; we don't care about the index here, so we pass the value 0 to indicate that the new atom is to be inserted as the last child of the specified type in the parent atom. The sixth and seventh parameters to QTInsertChi l d specify the n u m b e r of bytes of data to be added to the atom, along with a pointer to the atom data itself. The last p a r a m e t e r is a pointer to a variable of type QTAtom, in which QTInsertChi l d will return to us an identifier for the new atom; we don't need that information here, so we pass NULLin that parameter. We can create a hierarchy within an atom container by inserting parent atoms and then adding some children to those parents. We also call QTInsertChild to insert a parent atom, but we do not need to specify any data or data size; instead, we specify a variable of type QTAtom in w h i c h the identifier of the new parent atom is returned to us. Here's an example:
232
Chapter8 The Atomic Caf~
QTAtom myLi zardAtom; myErr = QTInsertChild(myAtomContainer, kParentAtoml sContai ner, kLizardData, 1, 1, O, NULL, &myLizardAtom) ;
Then we can insert a child atom into this parent atom, like this: myErr = QTInsertChild(myAtomContainer, myLi zardAtom, kLizardName, 1, 1, strl en (theLi zardName), theLizardName, NULL);
Note that the second p a r a m e t e r here is the parent atom that we just created. If we insert another atom (this time of type '1 z ln') into the parent and then repeat the whole process for the second lizard, we would have the atom structure shown in Figure 8.3.
Finding Atoms in A t o m Containers If we are given an atom container, it's almost as easy to get data out of it as it is to put data into it. First we need to find the atom whose data we want. The standard way to do this is to start at the top of the hierarchy and gradually descend until we find the parent of the desired atom. Then we can get an atom identifier of the target atom by calling the QTFindChildByID function. For example, if myLizardAtom is the parent atom for the atoms that hold the data about our lizard Avril, then we can get the n a m e atom by executing this code: myNameAtom = QTFindChi I dByID(myAtomContai ner, myLizardAtom, kLi zardName, 1, NULL); QTFindChildBylD actually inspects both the type and ID passed to it (not just the ID, as the name might suggest). The Movie Toolbox provides a n u m b e r of other functions that are useful for finding specific atoms, including QTCountChi 1dren0fType, QTFindChi 1dByIndex, QTGetNextChi I dType, and QTNextChi I dAnyType.
Getting A t o m Data Once we've found a leaf atom, we can get the data from that atom in several ways. If we want a copy of the atom data that will persist even after w e ' v e disposed of the atom container, we can call QTCopyAtomOataToHandle or
Atom Containers 2.33
QTCopyAtomDataToPtr, passing in a handle or pointer to a block of m e m o r y that's big enough to hold the leaf atom data. If, on the other hand, we just want to look at the atom data and don't need a copy of it, we can call the QTGetAtomDataPtr function, w h i c h returns a pointer to the actual leaf atom data. If you plan to make calls that might move memory, then you should call QTLockContainer before calling QTGetAtomDataPtr; then call QTUnlockContai ner w h e n you are done with the data pointer. If we want to retrieve our lizard's name, we could make this call: QTGetAtomDataPtr(myAtomContainer, myNameAtom, &myNameSize, &myNameData); If QTGetAtomDataPtr completes successfully, then myNameData points to the string of characters that make up the name, and myNameSize contains the size of that name.
Internet Connection Speed For our first real-life encounter with atom containers, let's consider h o w to get and set the user's Internet connection speed preference. The user can set a preference in the Connection Speed panel of the QuickTime Settings control panel, shown in Figure 8.4. QuickTime uses this setting for various purposes. For instance, if a user wants to play an alternate data rate movie file located on a remote server, QuickTime uses this connection speed to select the correct target movie. (An alternate data rate movie lile is a movie file that references other movies, each tailored for downloading across a connection of a certain speed.) We can retrieve the user's current QuickTime preferences by calling the GetQui ckTimePreference function, like this:
myErr = GetQuickTimePreference(ConnectionSpeedPrefsType, &myPrefsContainer) ; The first p a r a m e t e r specifies the kind of preference we wish to retrieve, and the second p a r a m e t e r is the address of an atom container in w h i c h the requested preference data is returned. It's up to us to dispose of that atom container w h e n we are done reading data from it. In the present case, w h e n we retrieve the Internet connection speed, the atom container contains an atom of type ConnectionSpeedPrefsType, whose data is structured as a record of type ConnectionSpeedPrefsRecord, defined like this:
struct ConnectionSpeedPrefsRecord { 1ong connecti onSpeed;
}~
234
Chapter8 The Atomic Caf~
Figure 8.4 The Connection Speedpanel. This record contains a single field that indicates the n u m b e r of bytes per second that the user's Internet connection can support. The file MoviesFormat.h defines a set of c o m m o n values: enum { kDataRate144ModemRate kDataRate288ModemRate kDataRateISDNRate kDataRateDuaIISDNRate kDataRateTIRate kDataRatelnfiniteRate
};
= = = =
1400, 2800, 5600, 11200,
= 150000L,
= Ox7FFFFFFF
Once we've received an atom container from GetQuickTimePreference, we can use the QTFindChildByID function to find the child atom of type ConnectionSpeedPrefsType. Then we get the atom data by calling the QTGetAtomDataPtr function. Finally, we can read the value stored in the connectionSpeed field, to find the current connection speed preference. We'll return this value
Internet Connection Speed 235
as the function result, w h e t h e r or not it's one of the predefined c o m m o n values. If any error occurs, however, we'll return the value kDataRate288ModemRate, which is a reasonable default. Listing 8.9 shows the complete function OTUti I s GetUsersConnectionSpeed. u
Listing 8.9 Getting the user's Internet connection speed preference. long QTUtils GetUsersConnectionSpeed (void) I
QTAtomContai ner QTAtom Connect i onSpeedPrefsRecord long long Ptr OSErr
myPrefsContai ner= NULL; myPrefsAtom = O; myPrefsRec; myDataSize = OL; mySpeed = kDataRate288ModemRate; myAtomData = NULL; myErr = noErr;
myErr = GetQuickTimePreference(ConnectionSpeedPrefsType, &myPrefsContainer) ; i f (myErr == noErr) { / / find the atom of the desired type myPrefsAtom = QTFindChildByID(myPrefsContainer, kParentAtomlsContainer, ConnectionSpeedPrefsType, 1, NULL); i f (myPrefsAtom ! = O) { / / read the data contained in that atom and verify that the data is of the / / size we are expecting QTGetAtomDataPtr(myPrefsContainer, myPrefsAtom, &myDataSize, &myAtomData); i f (myDataSize == sizeof(ConnectionSpeedPrefsRecord)) { / / read the connection speed myPrefsRec = *(ConnectionSpeedPrefsRecord *)myAtomData; mySpeed = myPrefsRec,connecti onSpeed;
}
QTDisposeAtomContai ner (myPrefsContai ner); return (mySpeed) ;
Note that we haven't performed any endian swapping on the value we read from the connection speed preferences record. That's because the data in this particular atom container is stored in native-endian format. This is an exception to the general rule that data in atom containers is big-endian. A user's QuickTime preferences are not designed to be moved from machine to machine, so there is no need to enforce big-endian byte ordering.
236
Chapter 8 The Atomic Caf~
Listing 8.10 shows how we can set a user's Internet connection speed. In general, we should let the user decide the connection speed preference, but it can sometimes be useful to do this programmatically. Listing 8.10 Setting the user's Internet connection speed preference. OSErr QTUtils SetUsersConnectionSpeed (long theSpeed)
{
m
QTAtomContainer Connecti onSpeedPrefsRecord OSErr
myPrefsContainer = NULL; myPrefsRec; myErr = noErr;
myErr = QTNewAtomContainer (&myPrefsContai ner); i f (myErr == noErr) { . myPrefsRec.connectionSpeed = theSpeed; myErr = QTInsertChild(myPrefsContainer, kParentAtomlsContainer, ConnectionSpeedPrefsType, 1, O, si zeof (Connecti onSpeedPrefs Record), &myPrefsRec, NULL); i f (myErr == noErr) myErr = SetQuickTimePreference(ConnectionSpeedPrefsType, myPrefsContainer) ; QTDisposeAtomContai ner (myPrefsContai ner) ; return (myErr) ;
QTUtils SetUsersConnectionSpeed creates a new atom container, inserts a single child atom into the container that holds the desired speed, and then passes that container to the SetQuickTimePreference function. Once SetQuickTimePreference returns, we can safely call QTDisposeAtomContainer to dispose of the atom container we created. u
Movie Tracks You might recall that in Chapter 3, "Out of Control," we saw how to write an application that plays one QuickTime movie inside of another QuickTime movie. The embedded movie (what we then called the "picture-in-picture movie") could have looping characteristics different from those of the main movie. For example, the embedded movie could keep looping over and over while the main movie played through once and then stopped. And, in theory, the embedded movie could play at twice its normal speed, while the
Movie Tracks 237
Figure 8.5 A child movie inside of a parent movie.
main movie played at, say, half its normal speed. (We didn't actually provide this alternate speed capability, but it would be easy enough to add.) The only drawback to this was that we needed the special playback application QTMooVToolbox to make it all happen. Wouldn't it be nice if we could create movie files with these capabilities, so that they would play back using any QuickTime-savvy application? This is precisely what's offered in QuickTime 4.1 with the introduction of movie tracks managed by the movie media handler. By adding movie tracks to an existing QuickTime movie, we can effectively embed an entire QuickTime movie into that movie. (This capability is sometimes called the movie-in-movie capability; the embedded movie is also called the child movie, while the main movie is also called the parent movie.) Figure 8.5 shows one movie embedded within another movie using a movie track. Remember that the looping characteristics and playback rate of a movie are associated with the movie's time base. Prior to QuickTime 4.1, it was possible to create movies with overlaid video tracks, but all the tracks in the movie shared the same time base. The time base of the overlaid track is slaved to that of the other tracks. What movie tracks bring to the table is the ability to have nonslaved time bases in a single movie. That is to say, each child movie can have its own time base, resulting in looping and playback rate characteristics independent of those of the parent movie.
Adding a Movie Track to a Movie So let's see how to create movie tracks. Suppose that theWindowObject is a window object for an open QuickTime movie file and that theDataRef and
238
Chapter 8 The Atomic Caf~
theDataRefType are a data reference and a data reference type for some other QuickTime movie file. Then we can call the QTMIM_AddMovieTrack function defined in Listing 8.11 to add to that open movie a movie track that references that file. (Once again, we'll postpone discussing data references to the next chapter; for now, all we need to k n o w is that they pick out QuickTime movie files, either on the local machine or elsewhere on the Internet.) Listing 8.11 Adding a movie track to a QuickTime movie. OSErr QTMIM AddMovieTrack (WindowObject theWindowObject, OSType theDataRefType, Handle theDataRef) m
Movie Track Media OSErr if
myMovie myTrack myMedia myErr =
= NULL; = NULL; = NULL; paramErr;
((theWindowObject : : NULL) goto bai I ;
II
/ / the parent movie / / the movie track / / the movie track's media
(theDataRef := NULL))
myMovie = (**theWindowObject).fMovie; / / create the movie track and media myTrack = NewMovieTrack(myMovie, FixRatio(kChildMovieWidth, 1), FixRatio(kChildMovieHeight, 1), kFulIVolume) ; myErr = GetMoviesError() ; i f (myErr ! = noErr) goto bai I ; myMedia = NewTrackMedia(myTrack, MovieMediaType, kMovieTimeScale, NULL, 0); myErr = GetMoviesError() ; i f (myErr ! = noErr) goto bai I ; / / create the media sample(s) myErr = Begi nMedi aEdi ts (myMedia) ; i f (myErr ! = noErr) goto bai I ; myErr = QTMIM AddMovieTrackSampl eToMedi a (theWi ndowObject, myMedia, theDataRefType, theDataRef); i f (myErr != noErr) goto bai I ; m
myErr : EndMediaEdi ts (myMedia) ; i f (myErr ! = noErr) goto bai I ;
Movie Tracks 2 3 9
/ / add the media to the track myErr = InsertMedialntoTrack(myTrack, O, O, GetMediaDuration(myMedia), fixed1); bail 9 return (myErr) ;
}
There is absolutely nothing new about this function. It's virtually identical to the function QTMM_CreateVideoMovie that we e n c o u n t e r e d in an earlier chapter (Chapter 6, "Doug's 1st Movie"). The only real difference is that we've created a media of type MovieMediaType; also, here we call QTMIM_AddMovieTrackSampleToMedia to add media samples to the new track, while earlier we called QTMM_AddVideoSampl esToMedi a.
Creating a M o v i e Track M e d i a Sample By now you might be wondering w h a t this has to do with atom containers. The answer is simple: the media sample for a movie track consists of an atom container whose atoms specify the movie to be e m b e d d e d in the main movie, as well as some of the playback characteristics of the e m b e d d e d movie. In other words, the function QTMIM_AddMovieTrackSampl eToMedi a needs only to create an appropriate atom container and pass that container to the AddMedi aSampl e function. We'll begin, therefore, by calling QTNewAtomContainer to create a new atom container; since this container will serve as our media sample, we'll call it mySampl e: myErr = QTNewAtomContainer(&mySample) ;
Into this new atom container, we want to put an atom of type kMovieMediaDataReference, whose data consists of the data reference type and the data
reference of the movie file that is to be the e m b e d d e d movie. We can create the atom data like this" myData = NewPtrClear(sizeof(OSType) + GetHandleSize(theDataRef)) ; myType = EndianU32 NtoB(theDataRefType); BlockMove(&myType, myData, sizeof(OSType)) ; BlockMove(*theDataRef, myData + sizeof(OSType), GetHandleSize(theDataRef)) ;
Then we can insert the atom into the atom container by calling QTInsertChild: myErr = QTlnsertChild(mySample, kParentAtomlsContainer, kMovieMediaDataReference, 1, 1, GetPtrSize(myData), myData, NULL);
240
Chapter8 The Atomic Caf~
At this point, we could call AddMediaSample to add the atom container mySample as the single media sample of the movie track. But we would like the embedded movie to start playing automatically w h e n the parent movie reaches the start time of the movie track, which is not the default behavior. To have the embedded movie automatically start playing, we need to add another atom to the atom container, of type kMovieMediaAutoPlay. myBool ean = true; myErr = QTInsertChild(mySample, kParentAtomlsContainer, kMovieMediaAutoPlay, 1, I, sizeof(myBoolean), &myBoolean, NULL);
Now we can create a sample description and add the atom container to the movie track media. Listing 8.12 shows our function OTMIM_AddMovieTrackSampleToMedia for adding a media sample to a movie track. Listing 8.12. Adding a sample to the movie track media. OSErr QTMIM_AddMovieTrackSampl eToMedia (WindowObject theWindowObject, Media theMedia, OSType theDataRefType, Handle theDataRef)
(
#pragma unused(theWi ndowObject) QTAtomContai ner QTAtom SampleDescriptionHandle Ptr OSType Boolean OSErr
mySample = NULL; myRegionAtom; mylmageDesc = NULL; myData = NULL; myType; myBool ean; myErr = paramErr;
/ / create a new atom container to hold the sample data myErr = QTNewAtomContainer (&mySample) ; i f (myErr l= noErr) goto bai I ; / / concatenate the data reference type and data reference into a single block of data myData = NewPtrClear(sizeof(OSType) + GetHandleSize(theDataRef)) ; i f (myData == NULL) goto bai I ; / / convert the data to big-endian format myType = EndianU32 NtoB(theDataRefType); D
BlockMove(&myType, myData, sizeof(OSType)) ; BlockMove(*theDataRef, myData + sizeof(OSType), GetHandleSize(theDataRef)) ;
Movie Tracks 24'11
/ / add an atom of type kMovieMediaDataReference to the atom container myErr = QTInsertChild(mySample, kParentAtomlsContainer, kMovieMediaDataReference, 1, 1, GetPtrSize(myData), myData, NULL); i f (myErr ! = noErr) goto bai I ; / / add an auto-start atom myBool ean = true; myErr = QTInsertChild(mySample, kParentAtomlsContainer, kMovieMediaAutoPlay, 1, 1, sizeof(myBoolean), &myBoolean, NULL); i f (myErr ! = noErr) goto bai I ; / / create a sample description myImageDesc = (SampleDescriptionHandle)NewHandleClear(sizeof(SampleDescription)) ; i f (mylmageDesc == NULL) goto bail ; (**myImageDesc).descSize = sizeof(SampleDescription) ; (**my ImageDesc). dataFormat = MovieMedi aType; myErr = AddMedi aSample( t heMedi a, mySample, O, GetHandleSize( (Handl e)mySample), GetMovi eDurat i on (GetTrac kMovi e (GetMedi aTrac k (theMedi a) ) ), myImageDesc, 1, O, NULL); bail: i f (myData l= NULL) Di sposePtr (myData) ; i f (mylmageDesc ! = NULL) Di sposeHandl e ( (Handl e)mylmageDesc) ;
242
Chapter8 The Atomic Caf~
i f (mySample ! = NULL) QTDi sposeAtomContai ner (mySample) ; return (myErr) ;
Notice that, as hinted at earlier, we call GetHand]eSize to get the size os the atom container when we call AddMediaSamp] e.
T h e Code In this chapter, our sample code is scattered across four different sets of files. The updated version of QTInfo is called QTInfoPlus and includes a new version of the QTInfo MakeFi]ePreview function and all the utilities that we used to access the atoms in a QuickTime movie file. The code for creating shortcut movie files is contained in the snippet QTShortcut.c. The code for getting and setting the user's Internet connection speed preference is contained in the file QTUtilities.c (which has been part of every project we've developed so far). Finally, the code for adding movie tracks to QuickTime movies is contained in the project for the sample application QTMovieTrack. QTMovieTrack allows the user to configure a large number of settings for the new movie track, in addition to the auto-playback setting (which we considered earlier). Figure 8.6 shows the dialog box that QTMovieTrack displays to allow the user to configure a new movie track. D
Figure 8.6 QTMovieTrack'sMovie Track Propertiesdialog box. The Code 2431
Conclusion QuickTime tries very hard to insulate us from having to work directly with the kinds of atoms that comprise movie files {the so-called classic, or chunk, atoms]. The Movie Toolbox provides an extensive set of high-level routines that we can use to create new movie files, open existing movie files, edit movie files, and so forth. Nevertheless, we've seen that there are occasions w h e n we do need to interact with atoms directly. A good example of this concerns adding a file preview to a single-fork movie file. QuickTime currently provides no API to do this, so we are forced to w o r k with the file data--the atoms--directly. Similarly, if we want to create a shortcut movie file on a machine that's running a version of QuickTime prior to version 4.0, we need to work with atoms. By contrast, we'll encounter atom containers and their associated atom container atoms at virtually every forward step in our journey through QuickTime. Atom containers and their children provide an easy way to maintain hierarchical data, and they're backed by an extensive programming interface. So atom containers are now the repository of choice for storing and exchanging data. We'll see them used in media samples, tween tracks, input maps, musical instruments, wired actions, video effect tracks, and for a large n u m b e r of other uses. Internet connection speed preferences and movie tracks are just the tip of the ice floe.
2414 Chapter8 The Atomic Caf~
Somewhere I'll Find You
Introduction In the previous few chapters, we've learned that a movie is composed of tracks and that each track is associated with one specific kind of media data. During movie playback, QuickTime uses a media handler (a component of type MediaflandlerType) to interpret the media data and present it to the user in the appropriate manner. For example, if the media data for some particular track consists of compressed video data, the video media handler calls the decompressor specified in the image description and then draws the decompressed frames in the appropriate location. A media handler, however, does not typically concern itself with reading the media data from the movie file (or from wherever else the media data is stored). Instead, the media handler gets that data from a data handler (a component of type DataHandlerType), which is responsible for reading and writing a media's data. In other words, a data handler provides data input and output services for a media handler and for other parts of QuickTime. We identify a source of media data to a data handler by providing a data reference. As we'll see shortly, QuickTime currently includes five standard data handlers. Each data handler works with one specific sort of data reference. For instance, the URL data handler expects data references that are handles to URLs. That is to say, a URL data reference is a handle to a block of data that contains a NULL-terminated string of characters. The other data handlers expect their references in other forms. A typical movie file contains data references to its media data in a data information atom, which is nested deep inside each track atom in the movie atom. In the previous chapter, we saw that a shortcut movie file contains a data reference atom that identifies an entire movie file. Data references can in fact pick out any kind of data, not just media data. In general, if we want to tell QuickTime where to find some data or where to put some data, we'll use a data reference to do so.
245
Figure 9.1
The Test menu of QTDataRef.
In this chapter, we're going to see h o w to work with each of the five standard data handlers. At the very simplest level, this involves nothing more than creating an appropriate data reference and putting that reference into a file (as we did in the last chapter) or passing it to a Movie Toolbox function like NewMovieFromDataRef. So we'll begin by learning how to create data references and call a few of the FromDataRef functions. Then we'll take a look at some of the functions that we can use to work with data handlers directly. These are fairly low-level functions that we w o n ' t need to use very often. Here, for fun, we'll see how to use them to write a general-purpose, asynchronous file transfer utility that relies solely on QuickTime APIs. Finally, toward the end of this chapter, we'll take a brief look at data reference extensions, which are blocks of additional data that we can associate with a data reference to assist QuickTime in working with the data picked out by the data reference. As we'll see, data reference extensions can be especially useful to graphics importers, to help them avoid having to take the time to validate some block of image data. Our sample application for this chapter is called QTDataRef; it illustrates how to work with data references and data handlers. Figure 9.1 shows the Test m e n u from QTDataRef.
Data Handler Overview W h e n QuickTime was first released, it included only one data handler, the lile data handler, which can read and write data stored in files on a local file system. QuickTime version 2.0 introduced the handle data handler, which allows the Movie Toolbox to work with data stored in m e m o r y and referenced with a handle. QuickTime version 2.5 added the resource data handler, which can read data stored in a file's resource fork. QuickTime 3.0 added the URL data handler to support reading data from locations specified using uniform resource locators fURLs). More recently, QuickTime 5 added the
246
Chapter 9 Somewhere I'll Find You
pointer data handler, which can w o r k with data stored in m e m o r y and referenced with a pointer. All data handlers are components of type DataHandlerType. Data h a n d l e r s are distinguished from one another by their c o m p o n e n t s u b ~ e s . The file Movi es.h defines constants for four of the five data handler subtypes: enum { HandleDataHandlerSubType ResourceDataHandlerSubType URLDataHandlerSubType PointerDataHandlerSubType
};
= = = =
FOUR CHAR CODE('hndl ' ) , FOUR CHAR CODE('rsrc'), FOUR CHAR CODE('url ' ) , FOUR CHAR CODE('ptr') D
And the file A] i ases. h defines the constant used for the file data handler: enum { rAl i asType
};
= FOUR CHAR CODE('alis')
QuickTime also includes several other data handlers that it uses for its own private purposes and for which there is currently no public API. We w o n ' t consider these private data handlers in this chapter, but you should at least know that they exist [so that, for example, you aren't surprised if you iterate through all components of type DataHandlerType and find more than five of them). A data reference is a handle to a block of m e m o r y that uniquely identifies the location of some media data for a QuickTime movie or some other data that QuickTime can manage. QuickTime currently provides support for five types of data references, one for each of the available data handlers. To let the cat out of the bag: 9 A file data reference is a handle to an alias record that specifies a file on a local storage volume (or on a remote storage volume m o u n t e d on the local machine). That is to say, a file data reference is an alias handle. Because the file data handler is of subtype rA] i asType and uses alias handles as its d a t a r e f e r e n c e s , it is often called the alias data handler. In a d d i t i o n , because it originally handled files on the Macintosh hierarchical file system (HFS), it is also sometimes called the HFS data handler. 9 A handle data reference is a handle to a 4-byte block of m e m o r y that holds a handle to some other block of data. That is to say, a handle data reference is a handle to a handle. 9 A resource data reference is a handle to an alias record to which two pieces of information have been appended, a resource type and a resource ID.
Data Handler Overview 247
The target data is found in the resource fork of the file specified by that alias record, in the resource of the specified type and ID.
9 A URL data reference is a handle to a NULL-terminated string of characters that comprise the URL. The string of characters should conform to the relevant Internet Engineering Task Force (IETF) specifications; in particular, some nonalphanumeric characters may need to be encoded using the hexadecimal equivalents of their ASCII codes (for instance, the space character should be encoded as "~20"). 9 A pointer data reference is a handle to a data structure of type PointerDataRefRecord, which specifies a location in m e m o r y and a length. In the following five sections, we'll investigate these five types of data references in more detail. Before we begin, however, let's introduce a bit of terminology that will be useful throughout this chapter. Let's call the block of memory to which a data reference is a handle the referring data. And let's call the data picked out by the data reference the target data (or just the target) of the data reference. So, for example, the referring data of a URL data reference is the string of characters, and the target data of a URL data reference is the data in the file picked out by that URL.
T h e File D a t a H a n d l e r We can use the file data handler to open movies that are specified using a file data reference, which is an alias handle. Listing 9.1 shows how to create a file data reference for a given file.
Listing 9.1 Creating a file data reference. Handle QTDR_MakeFileDataRef (FSSpecPtr theFile)
{
Handle
myDataRef = NULL;
QTNewAlias(theFile, (AliasHandle *)&myDataRef, true) ; return (myDataRef) ;
QTDR_MakeFi l eDataRef consists mainly of a call to the Movie Toolbox function QTNewA1i as, which returns, in the location specified by the second parameter, an alias handle for the file specified by the first parameter. The third parameter is a Boolean value that indicates whether to create a minimal or a full alias record. (A minimal alias record contains only the minimum infor-
248
Chapter 9 Somewhere I'll Find You
mation needed to find a file; it's generally m u c h faster to find the target of a minimal alias record, so that's w h a t we'll use here.) We could also have used the Alias M a n a g e r functions NewAlias (for a full alias record) or NewA]iasMinima] (for a m i n i m a l alias record) to create the file data reference. The principal advantage of using QTNewA]i as is that it r e t u r n s an alias handle even if the file specified by t h e F i l e doesn't yet exist. Both NewAlias and NewAliasMinimal r e t u r n an error (fnfErr)--and do not create an alias record--if the specified file does not exist. As we'll see soon, we sometimes w a n t to create data references for files that we h a v e n ' t yet created. {The Alias Manager does provide the NewAliasMinimalFromFullPath function that can create alias records for files that don't exist, but w e ' d r a t h e r not have to deal with full p a t h n a m e s just to do that.)
O p e n i n g a M o v i e File Let's consider a few examples of using file data references. First, w e can pass a file data reference to the NewMovieFromDataRef function, to achieve exactly the same effect as calling the OpenMovieFile and NewMovieFromFile functions. Listing 9.2 defines the function QTDR_GetMovieFromFi l e, w h i c h creates a file data reference and then retrieves the movie in the specified movie file.
Listing 9.2 Opening a file specified by a file data reference. Movie QTDR_GetMovieFromFile (FSSpecPtr theFile)
{
Movie Handle
myMovie = NULL; myDataRef= NULL;
myDataRef = QTDRMakeFileDataRef(theFile) ; i f (myDataRef l= NULL) { NewMovieFromDataRef(&myMovie, newMovieActive, NULL, myDataRef, rAliasType) ; Di sposeHandle (myDataRef) ;
}
return (myMovie) ;
The last two parameters to the NewMovieFromDataRef function specify, respectively, the data reference and the data reference type. Since we are passing it a file data reference, we set the data reference type to rA] i asYype. Note that we call Di sposeHandl e to dispose of the data reference once we are finished using it. By the time NewMovieFromDataRef returns, the Movie Toolbox will have m a d e a copy of the data reference, if necessary.
The File Data Handler
249
Creating a R e f e r e n c e M o v i e File Now let's turn to a more interesting example of using file data references. We learned in Chapter 6, "Doug's 1st Movie," that a movie file might not contain the media data referenced by the movie's tracks; instead, that media data might be contained in some other file. A file that contains some media data is a media/ile, and the file that contains the movie atom is the movie file. (For simplicity, let's assume that our movies have only one track, a video track.) W h e n the movie file and the media file are different files, the movie file is a reference movie file (because it refers to its media data and does not contain it). W h e n the movie file and the media file are the same file, the movie file is a self-contained movie lile. While, generally, we prefer to create self-contained movie files, it's useful to know how to create a reference movie file. (Reference movie files can be useful, for instance, if we want to share some media data among several QuickTime movies.) One way to do this is to pass a file data reference to the NewTrackMedia function. Recall that NewTrackMedi a is declared essentially like this: Media NewTrackMedia (Track theTrack, OSType mediaType, TimeScale timeScale, Handle dataRef, OSType dataRefType) ; The fourth and fifth parameters specify the data reference and the data reference type of the file (or other container) that is to hold the media data for the specified track. Previously, w h e n e v e r we called NewTrackMedia, we passed NULLand 0 in those parameters, to indicate that the media file should be the same as the movie file. Now we'll create a reference movie file simply by specifying a media file that is different from the movie file. We're going to define a function QTOR_CreateReferenceCopy that we can use to create a copy of an existing movie that contains the first video track in the original movie. The copy's movie atom will be contained in one file (theOstMovieFile), and its media data will be contained in some other file (theOstMediaFi l e). QTDR_CreateReferenceCopyhas this prototype" OSErr QTDR_CreateReferenceCopy (Movie theSrcMovie, FSSpecPtr theDstMovieFile, FSSpecPtr theDstMediaFile); The definition of QTDR_CreateReferenceCopy will look vaguely familiar, at least if you recall the sequence of moviemaking functions that we encountered in the QTMM_CreateVideoMovie function. It uses CreateMovieFile, NewMovieTrack, NewTrackMedia, BeginMediaEdits, EndMediaEdits, and AddMovieResource in the standard ways. There are only two important differences
250
Chapter 9 Somewhere I'll Find You
between QTDR_CreateReferenceCopy and QTMM_CreateVideoMovie. First, w e ' r e going to obtain the media data for the copy from the first video track in the existing movie; to do this, we'll call GetMovieIndTrackType and GetTrackMedia to get the media from the source movie:
mySrcTrack = GetMovielndTrackType(theSrcMovie, 1, VideoMediaType, movieTrackMediaType); mySrcMedia = GetTrackMedia(mySrcTrack) ; Then we'll call GetTrackDimensions and GetMediaHandlerDescription to obtain some information about the source track and its media:
GetTrackDimensions(mySrcTrack, &myWidth, &myHeight); GetMediaHandlerDescription(mySrcMedia, &myType, O, 0); W h e n we create the copy movie, we'll need this information to be able to specify the size of the new track and the type of the track's media. The second main difference between OTOR_CreateReferenceCopy and QTMM_CreateVideoMovie concerns the way we add media data to the new movie. Previously, we called an application-defined function to create the media samples and add them to the track's media (using AddMediaSample). Now, however, we've already got the media data for the new file--it's just the media data contained in the first video track of the source movie file. So, instead, we can use the Movie Toolbox function InsertTrackSegment to copy the media data from the source track to the new track, like this:
myErr = InsertTrackSegment(mySrcTrack, myDstTrack, O, GetTrackDuration(mySrcTrack), O) ; Here, InsertTrackSegment copies the entire source track {that is, starting at time zero and extending for the duration GetTrackDuration(mySrcTrack)) and inserts it into the destination track starting at time zero. The result is that the new media file will contain a copy of the source track's media data. There is one final detail we need to attend to. In order for the destination track to have the same visual characteristics as the source track, we also need to copy the source track matrix, clipping region, and graphics mode {among other things} into the destination track. Similarly, if the source track were a sound track, we would need to copy its volume, sound balance, and other sound characteristics into the destination track. We could copy the visual settings by calling GetTrackMatri x and SetTrackMatri x, GetTrackCl i pRgn and SetTrackClipRgn, and so forth. Better yet, the Movie Toolbox provides the CopyTrackSettings function that copies all these settings in one fell swoop:
CopyTrackSettings (mySrcTrack, myDstTrack) ;
The File Data Handler 251
Listing 9.3 shows our comp|ete definition of QTDR_CreateReferenceCopy.
Listing 9.3 Creating a reference movie file. OSErr QTDR_CreateReferenceCopy (Movie theSrcMovie, FSSpecPtr theDstMovieFile, FSSpecPtr theDstMediaFile)
{
Track Medi a Movie Track Medi a Handle Fixed OSType long short short OSErr
mySrcTrack = NULL; mySrcMedia = NULL; myDstMovie = NULL; myDstTrack = NULL; myDstMedia = NULL; myMediaRef = NULL; myWidth, myHeight; myType; myFlags = createMovieFileDeleteCurFile [ createMovieFileDontCreateResFile; myResRefNum = O; myResID = movieInDataForkResID; myErr = paramErr;
/ / get the f i r s t video track and media in the source movie mySrcTrack = GetMovielndTrackType(theSrcMovie, 1, VideoMediaType, movieTrackMediaType) ; i f (mySrcTrack == NULL) goto bai I ; mySrcMedia = GetTrackMedia(mySrcTrack) ; i f (mySrcMedia == NULL) goto bai I ; / / get some information about the source track and media GetTrackDimensions(mySrcTrack, &myWidth, &myHeight); GetMediaHandlerDescription(mySrcMedia, &myType, O, 0); / / create a f i l e data reference for the new media f i l e myMediaRef = QTDR_MakeFileDataRef(theDstMediaFi le) ; i f (myMediaRef == NULL) goto bai I ; / / create a f i l e for the destination movie data and create an empty movie myErr = FSpCreate(theDstMediaFile, sigMoviePlayer, MovieFileType, 0); i f (myErr != noErr) goto bai I ; / / create a f i l e for the destination movie atom myErr = CreateMovieFile(theDstMovieFile, sigMoviePlayer,
252
Chapter 9 Somewhere I'll Find You
smCurrentScript, myFlags, &myResRefNum, &myDstMovie) ; i f (myErr I = noErr) goto bai I ; / / assign the default progress proc to the destination movie SetMovieProgressProc(myDstMovie, (MovieProgressUPP)-l, O) ; / / create the destination movie track and media myDstTrack = NewMovieTrack(myDstMovie, myWidth, myHeight, kNoVolume); myErr = GetMoviesError() ; i f (myErr ! = noErr) goto bai I ; myDstMedia = NewTrackMedia(myDstTrack, myType, GetMediaTimeScale(mySrcMedia), myMediaRef, rAliasType) ; myErr = GetMoviesError() ; i f (myErr I = noErr) goto bai I ; / / copy the entire source track into the destination track; / / this copies the track's media samples into the destination media f i l e myErr = BeginMediaEdi ts (myDstMedia) ; i f (myErr ! = noErr) goto bai I ; myErr = InsertTrackSegment(mySrcTrack, myDstTrack, O, GetTrackDuration(mySrcTrack), i f (myErr ! = noErr) goto bai I ;
0);
CopyTrackSettings (mySrcTrack, myDstTrack) ; myErr = EndMediaEdi ts (myDstMedia) ; i f (myErr I= noErr) goto bai I ; / / add the movie atom to the data fork of the movie f i l e myErr = AddMovieResource(myDstMovie, myResRefNum, &myResID, NULL); bail: return (myErr) ;
}
We call the QTDR_MakeFileDataRef function to create a file data reference for the media file specified by the theDstMediaFi l e parameter, and we pass
The File Data Handler
253
Figure 9.2 The missing data dialog box. that data reference to the NewTrackMedia function, as described earlier. By default, QTDataRef n a m e s the new movie file untitled.mov and the new media file u n t i t l e d . d a t . W h e n a user tries to open untitled.mov, the Movie Toolbox looks for u n t i t l e d . d a t to find the movie's media data. If it cannot find that file, the Movie Toolbox displays the dialog box shown in Figure 9.2. One reason we prefer to create self-contained movie files is to ensure that the media data is always available, so the user w o n ' t ever have to see this dialog box. Before we move on, it's worth mentioning that the Movie Toolbox provides the AddEmptyTrackToMovie function, which we could use in Listing 9.3 instead of NewMovieTrack, NewTrackMedia, and CopyTrackSettings, like this: myErr = AddEmptyTrackToMovie(mySrcTrack, myDstMovie, myMediaRef, rAliasType, &myDstTrack) ; i f (myErr I= noErr) goto bai I ; myDstMedi a = GetTrackMedi a (myDstTrack) ;
AddEmptyTrackToMovie makes a copy of an existing track, either in the same movie or in a different movie; it doesn't actually copy the media data, but it does copy the track settings. The source code files accompanying this chapter provide an alternate version of the QTDRCreateReferenceCopy function that uses AddEmptyTrackToMovie.
The Handle Data Handler The handle data handler is used to read data from and write data to a location in memory. That location is specified using a Macintosh handle. A handle data reference is a handle to that handle. Listing 9.4 shows how to create a handle data reference.
254
Chapter 9 Somewhere I'll Find You
Listing 9.4 Creating a handle data reference. Handle QTDR_MakeHandleDataRef (Handle theHandle)
{
Handle
myDataRef = NULL;
myDataRef = NewHandleClear(sizeof(Handle)) ; i f (myDataRef ! = NULL) BlockMove(&theHandle, *myDataRef, sizeof(Handle)) ; return (myDataRef) ;
Here we allocate a relocatable block of m e m o r y that is the size of a handle (4 bytes} and then copy the handle passed to the function into that block of memory. The result is just what we want, a handle to the original handle. For an even simpler routine, we can replace the middle three lines of code by this one line: PtrToHand(&theHandle, &myDataRef, sizeof(Handle)) ;
The Memory Manager function PtrToHand allocates a new relocatable block of m e m o r y of the specified size and then copies the data specified by its first parameter into that block. In a little while, we'll encounter PtrAndHand, a cousin of PtrToHand that appends the data in a pointer to an existing handle. The handle data handler is useful for m a n y tasks. It's useful for playing movies that can fit entirely into RAM, and it's useful for handling images w h e n the image data resides in m e m o r y and not in a file. In the latter case, we can just create a handle data reference from the handle that holds the image data and pass it to GetGraphicsImporterForDataRef to get a graphics importer that can manage the image data. Similarly, to play a movie stored in RAM, we can create a handle data reference and pass it to NewM0vieFromOataRef. In this case, the block of m e m o r y referenced by the handle must contain the movie data and the movie atom. To create a movie whose data is stored in RAM, we could use NewTrackMedia as illustrated in the previous section, passing it a handle data reference instead of a file data reference. Or, even more simply, we can exploit the ability of the FlattenMovieOata function to flatten a movie into a location specified by a data reference instead of by a file system specification record. The third parameter to F1 attenMovieData is declared as a pointer to an FSSpec record, but we can set the flag flattenFSSpecPtrIsOataRefRecordPtr to instruct it to interpret that parameter as a pointer to a data reference record, defined by the DataReferenceRecord data type:
The Handle Data Handler 255
struct DataReferenceRecord { OSType Handle
}~
dataRefType; dataRef;
So all we need to do is create a handle data reference, fill in a data reference record with the appropriate information, and then pass the address of that record to FlattenMovieData in place of the FSSpecPtr. Listing 9.5 shows an excerpt from our OTApp_Hand]eMenu function that handles the Create RAM Copy and Play m e n u item. Listing 9.5 Creating a movie in RAM. case IDM CREATE RAM COPY AND PLAY: i f (myMovie l= NULL) { Movie myNewMovie = NULL; Handle myDataRef = NULL; Handle myHandle = NULL; DataRefe ren ceRecord myDataRe fReco rd; myHandle = NewHandleClear(O) ; i f (myHandle == NULL) goto bai] ; myDataRef = QTDR_MakeHandleDataRef(myHandl e) ; i f (myDataRef == NULL) goto bai] ; myDataRefRecord.dataRefType = HandleDataHandl erSubType; myDataRefRecord.dataRef = myDataRef; myNewMovie = Fl attenMovi eData (myMovie, fl attenFSSpecPtr I sDataRefRecordPt r, ( FSSpec Pt r) &myDataRefReco rd, sigMoviePl ayer, smSystemScri pt,
OL);
i f (myNewMovie ! = NULL) { QTDR_Pl ayMovi eFromRAM(myNewMovi e) ; Di sposeMovi e (myNewMovie) ;
}
bail: i f (myHandle ! = NULL) Di sposeHandl e (myHandle) ;
256
Chapter 9 Somewhere I'll Find You
i f (myDataRef l= NULL) Di sposeHandl e (myDataRef) ;
In this case, once w e ' v e created the movie in RAM, w e call the function QTDR_PlayMovieFromRAM to play the movie in a w i n d o w on the screen. T h e n we dispose of the n e w movie and the handle that contains the movie data, along w i t h the h a n d l e data reference.
The Resource Data Handler The resource data h a n d l e r was i n t r o d u c e d in Q u i c k T i m e version 2.5 to allow data to be read from a resource in a file's resource fork. Listing 9.6 shows how to create a resource data reference. Listing 9.6 Creating a resource data reference. Handle QTDR MakeResourceDataRef (FSSpecPtr theFile, OSType theResType, SInt16 theResID)
{
Handle OSType SInt16 OSErr
myDataRef = NULL; myResType; myResID; myErr = noErr;
myDataRef = QTDR_MakeFileDataRef(theFi le) ; i f (myDataRef == NULL) goto bai I ; / / append the resource type and ID to the data reference myResType = EndianU32 NtoB(theResType); myResID = EndianS16 NtoB(theResID); myErr = PtrAndHand(&myResType, myDataRef, sizeof(myResType)) ; i f (myErr == noErr) myErr = PtrAndHand(&myResID, myDataRef, sizeof(myResID)) ; bail 9 i f (myErr l : noErr) { i f (myDataRef l: NULL) Di sposeHandl e (myDataRef) ; myDataRef = NULL;
}
return (myDataRef) ;
The Resource Data Handler
257
In QTDR_MakeResourceDataRef, we begin by creating a file data reference to the specified file. Then we call PtrAndHand to append the resource type to the referring data of that data reference, and then we call PtrAndHand once again to append the resource ID. Note that the resource type and ID must be converted to big-endian format before being appended to the referring data. We w o n ' t spend too m u c h time considering the resource data handler, largely because we prefer not to keep our movie or image data in resource files (so that it's easily transportable to non-Macintosh operating systems). To show you that it works on Macintosh resource files, I've added the m e n u item Open Resource Movie to the QTDataRef sample application; I've also included the file ResBased.mov, which contains a movie stored in a resource. There is another reason w h y the resource data handler is of limited interest to us" it can read data from resource files but cannot write data to them. To see this, let's suppose that myDataRef is a resource data reference. Then we can call the GetDataHandler function like this: myComponent = GetDataHandler(myDataRef, ResourceDataHandl erSubType, kDataHCanWrite) ;
GetDataHandler returns the best data handler for the specified data reference and data handler type that provides the services specified by the third parameter. In this case, we're asking for a resource data handler that can write data. After this line of code completes, however, the value r e t u r n e d in myComponent will be NULL, indicating that there is no such resource data handler. The last reason we're going to ignore the resource data handler in the future is perhaps the most obvious: if we do want to access some movie or image data stored in a resource, we can simply load that data into m e m o r y (by calling GetResource) and then use the handle data handler. So the resource data handler is largely redundant.
T h e URL D a t a H a n d l e r We can use QuickTime to open movies and images that are specified using URLs. A URL is the address of some resource on the Internet or on a local disk. Typically, a URL is a string of characters like "http://www.apple.com." The initial portion of the URL, which precedes the first colon (:), is the URL's scheme or protocol. In this case, the scheme is "http" for the hypertext transfer protocol. QuickTime provides data handlers that can w o r k with URLs whose scheme is "http," "ftp" (file transfer protocol), "rtsp" (real-time
258
Chapter9 Somewhere I'll Find You
streaming protocol), or " f i l e " (picking out a file on the local file system). Note that there really isn't just one URL data handler; there are in fact several data handlers that support URLs. For instance, the file data handler will ultimately be used to handle URLs whose scheme is "file." Still, we access these data handlers using URL data references. As we've already seen, a data reference for the URL data handler is a handle to the NULL-terminated string of characters that comprise a URL. So it's relatively easy to create a URL data reference" just allocate a relocatable block of the appropriate size and copy the URL into that block. Listing 9.7 defines the function QTDR MakeURLDataRef, which creates a URL data reference for a given URL. Listing 9.7 Creating a URL data reference. Handle QTDR_MakeURLDataRef (char *theURL)
{
Handle Size
myDataRef = NULL; mySize = O;
/ / get the size of the URL, plus the terminating null byte mySize = (Size)strlen(theURL) + 1; i f (mySize == 1) goto bai I ; / / allocate a new handle and copy the URL into the handle myDataRef = NewHandleClear(mySize) ; i f (myDataRef ! = NULL) BlockMove(theURL, *myDataRef, mySize) ; bail 9 return (myDataRef) ;
}
If a URL picks out a movie file, we can call QTDR_MakeURLDataRefto create a URL data reference for it and then pass that data reference to the NewMovieFromDataRef function to open the specified movie file. Listing 9.8 defines the function QTURL_NewMovieFromURLthat takes a URL and returns a movie identifier for the movie addressed by that URL. QTDRGetMovieFromURL is just like QTDR GetMovieFromFi l e, except that it uses URL data references.
The URL Data Handler 2 5 9
Listing 9.8 Opening a movie specified by a URL. Movie QTDR_GetMovieFromURL (char *theURL)
{
Movie Handle
myMovie = NULL; myDataRef= NULL;
myDataRef = QTDR_MakeURLDataRef(theURL); i f (myDataRef != NULL) { NewMovieFromDataRef(&myMovie, newMovieActive, NULL, myDataRef, URLDataHandlerSubType); Di sposeHandl e (myDataRef) ;
}
return (myMovie) ;
The QTDR_GetMovieFromURL function is a large part of what we need to handle the Open URL m e n u item (supported both by QuickTime Player and by our sample application QTDataRef). But it isn't quite all of what we need. First, of course, w h e n the user selects Open URL, we need to obtain a URL from him or her. QuickTime Player displays the dialog box shown in Figure 9.3, which contains space to type in a URL, as well as a pop-up m e n u containing a list of recently opened URLs. For the moment, we'll be content to display the dialog box shown in Figure 9.4, which does not provide the pop-up menu. (Providing a pop-up m e n u or some other kind of list for recently accessed URLs is a good idea, however, since URLs are often longer than 255 characters, which is the most our current code will support.) The code to display and manage this dialog box is contained in the function QTDR_GetURLFromUser, which we w o n ' t consider in detail here; it's really quite similar to the function QTInfo_EditAnnotation, which we considered in
Figure 9.3 The Open URL dialog box of QuickTime Player.
260
Chapter 9 Somewhere I'll Find You
Figure 9.4 The Open URL dialog box of QTDataRef.
Chapter 7, "The Informant." It's also useful to get the basename of the URL so that our movie window has a title {the basename is the portion of the URL following the rightmost URL separator). See the file QTOataRef.c for the function QTOR_fietURLBasename, which we use to find that basename.
The Pointer Data Handler The pointer data handler can be used to read data from a location in memory. While the handle data handler references memory using a Memory Manager Handle data type, the pointer data handler references memory using a memory address and a byte count. The memory address can be specified using a Memory Manager Ptr data type, but it does not have to be. In other words, the block of memory specified using a pointer data reference does not need to be a block that was allocated using the Memory Manager. A pointer data reference is a handle to a pointer data reference record, which is defined by the PointerDataRefRecord data type: struct PointerDataRefRecord { void *data; Size dataLength;
};
typedef PointerDataRefRecord *PointerDataRefPtr; typedef PointerDataRefPtr *PointerDataRef;
The Pointer Data Handler 261
The data field is the address of the first byte of a block of data, and dataLength is the length of that block of data. Listing 9.9 shows how to create a pointer data reference.
Listing 9.9 Creating a pointer data reference. Handle QTDR_MakePointerDataRef (void *thePtr, Size theLength)
{
PointerDataRef
myDataRef = NULL;
myDataRef = (PointerDataRef)NewHandleClear(sizeof(PointerDataRefRecord)) ; i f (myDataRef ! = NULL) { (**myDataRef).data = thePtr; (**myDataRef).dataLength = theLength;
}
return( (Handl e)myDataRef) ;
File Transfer We've learned that QuickTime supplies a data handler that can read data from remote locations specified by a URL and a data handler that can write data into files on the local file system. We can use both of these data handlers at the same time to read data stored remotely on the Internet and write it into a local file. This gives us, in effect, a network file transfer capability that operates using only QuickTime APIs. Moreover, QuickTime supports calling these data handlers asynchronously so that our application can perform other processing while the file transfer is taking place. In this section, we'll see how to do all this. Our ulterior motive here is to get a glimpse of the lower-level functions supported by data handlers. Hitherto, we've pretty much always used data handlers indirectly, by passing data references to Movie Toolbox or ICM functions, or simply by embedding data references in files. Now we want to see how to work with data handlers directly. In overview, our file transfer will proceed like this: get an instance of the URL data handler and configure it to copy data from a remote file into a memory buffer. Then get an instance of the file data handler and configure it to copy data from that buffer into a local file. Then keep copying data into and out of the buffer until the entire remote file has been copied. Our file transfer code is going to rely on a few global variables, declared like this:
262
Chapter 9 Somewhere I'll Find You
Ptr Component Ins tance ComponentInstance DataHComplet i onUPP DataHCompl et i onUPP long long Boolean
gDataBuffer = NULL; gDataReader = NULL; gDataWri ter = NULL; gReadDataHCompletionUPP = NULL; gWriteDataHCompletionUPP = NULL; gBytesToTransfer = OL; gBytesTransferred = OL; gDoneTransferring = false;
The variables gDataReader and gDataWri t e r are the component instances of the URL data handler that reads data and the file data handler that writes data. The variable gDataReader puts data into the buffer gDataBuffer, w h e n c e gDataWriter gets the data that it writes into the local file. The asynchronous nature of the file transfer is achieved largely by two completion functions, to which gReadDataHCompleti onUPP and gWri teDataHCompl eti onUPP are universal procedure pointers. Finally, the global variables gBytesToTransfer, gBytesTransferred, and gDoneTransferring keep track of information while the transfer is under way.
Creating the Local File The first thing we need to do, of course, is create the local file into which the remote file data is to be copied. Let's suppose that theFile is a file system specification for the local file (which we perhaps got from the user by calling our framework function QTFrame_PutFi l e). We should first delete that file, if it already exists, by calling FSpDelete: FSpDelete(theFi I e) ;
If the specified file doesn't exist, FSpDelete will return the error code fnfErr, w h i c h we can safely ignore. Then we can call FSpCreate to create a new empty file, like this: myErr : FSpCreate(theFile, kTransFileCreator, kTransFileType, smSystemScri pt) ;
[Note that we are hard-coding the file's type and creator codes here; I'll leave it as an exercise for the reader to concoct a more flexible way to set these values.)
File Transfer 2 6 3
Opening and Configuring Data Handlers Before we can w o r k with a data handler, we need to open an instance of the appropriate data handler component. We saw earlier that we can find a particular data handler by calling GetDataHandler, passing it a data reference, a type, and a set of flags that indicate the data-handling services we need it to provide. If theURL is a C string that specifies the remote file and t h e F i l e is a pointer to a file system specification for the local file into which the remote file data is to be copied, we can create the required data references like this: Handle myReaderRef = QTDR_MakeURLDataRef(theURL) ; Handle myWriterRef = QTDR_MakeFileDataRef(theFi le) ;
And we can open the appropriate data handlers with this code: gDataReader = OpenComponent(GetDataHandl er(myReaderRef, URLDataHandlerSubType, kDataHCanRead)) ; gDataWri ter = OpenComponent(GetDataHandl er(myWri terRef, rAl i asType, kDataHCanWrite) ) ;
As you can see, w e ' r e asking for a URL data handler that can read data and a file data handler that can write data. Once w e ' v e got our data handler instances, we need to configure them by telling t h e m which data references they are going to w o r k with. We also need to have t h e m open a connection to the targets of those data references. We can set the data references by calling DataHSetDataRef, like this: myErr = DataHSetDataRef(gDataReader, myReaderRef) ; myErr = DataHSetDataRef(gDataWriter, myWriterRef) ;
Then we can open the appropriate connections by calling DataH0penForRead and DataHOpenForWri te: myErr = DataHOpenForRead(gDataReader) ; myErr = DataHOpenForWrite(gDataWriter) ;
Transferring Data Synchronously It might seem like we haven't done m u c h work yet, but (believe it or not) we are ready to begin transferring data from the remote file into the local file. At this point, we have a choice: we can transfer the data synchronously (that is, waiting for all the data to arrive before continuing with any other work) or asynchronously. Ultimately, we want to have our transfers proceed asynchronously, but let's take a m o m e n t to see how to do t h e m synchronously.
264
Chapter9 Somewhere I'll Find You
To perform a synchronous transfer, we can call DataHGetData and DataHPutData. These functions require the intermediate buffer to be accessed by a handle (not by a pointer, as with asynchronous transfers). We can call DataHGetFileSize to see how m a n y bytes we need to transfer and then allocate a handle of that size: myErr = DataHGetFileSize(gDataReader, &gBytesToTransfer) ; Handle gDataBuffer = NewHandleClear(gBytesToTransfer);
If gDataBuffer is successfully created, we can transfer the remote file to the local file with these four lines of code: DataHGetData(gDataReader, gDataBuffer, OL, OL, gBytesToTransfer); DataHCl oseForRead(gDataReader) ; DataHPutData(gDataWriter, gDataBuffer, OL, NULL, gBytesToTransfer); DataHCl oseForWri te (gDataWri ter) ;
All we need to do is fetch the remote data into the intermediate buffer, close the connection to the remote file, write the data into the local file, and then close the connection to the local file. So there you have it: with barely a dozen lines of code, w e ' v e managed to copy a file located somewhere out on the Internet into a local file. The downside here is that the transfer occurs synchronously and is limited to files that can fit entirely into RAM. Let's remove these two limitations.
Transferring Data Asynchronously We can remove the limitation on file size rather simply, by allocating an intermediate buffer of a set size and then reading and writing chunks of data of that size. We'll allocate a buffer that is 10 Kbytes, like this: #define kDataBufferSize
1024"10
ptr gDataBuffer = NewPtrClear(kDataBufferSize);
So all we need to do is read a c h u n k of data of size kDataBufferSize, write that chunk of data, read another c h u n k of data, write that chunk, and so on until the entire remote file is transferred. Of course, eventually we'll probably end up with a c h u n k that's smaller than kOataBufferSize, so we'll need to keep track of how m u c h of the file remains to be transferred and adjust our reads accordingly. We can achieve an asynchronous transfer by using the functions DataHReadAsync and DataHWrite to read and write data. These functions queue up a read or write request to the data handler and then return immediately,
File Transfer 265
without waiting for the request to be serviced. The request will be serviced at some later time, when we call DataHTask to task the data handler. Once the request is serviced, the data handler executes a data handler completion function that we specify when we call DataHReadAsync or DataHWrite. A data handler completion function takes three parameters: a pointer to the buffer into which data was written or from which data was read, an application-specific reference constant, and an error code. We'll ignore the error code and use the reference constant to hold the number of bytes just written or read by the data handler. We begin the file transfer by reading some data from the remote file. We could simply call OataHReadAsync directly, passing it the appropriate parameters. Instead, however, we'll be a bit clever here and call our write completion function QTDR_WriteDataCompletionProc, passing it parameters that indicate that we've just successfully finished writing 0 bytes" QTDR_WriteDataCompletionProc(gDataBuffer, OL, noErr); The QTDR_WriteDataCompletionProc function (defined in Listing 9.10) contains code for figuring out how many bytes to request and then for issuing
the appropriate read request. Listing 9.10 Responding to a write operation. PASCAL_RTN voi d QTDR_WriteDataCompl et i onProc (Ptr theRequest, long theRefCon, OSErr theErr)
{
#pragma unused(theErr) long myNumBytesToRead; wide myWide; / / increment our t a l l y of the number of bytes written so far gBytesTransferred += theRefCon; i f (gBytesTransferred < gBytesToTransfer) { / / there is s t i l l data to read and write, so schedule a read operation / / determine how big i f (gBytesToTransfer myNumBytesToRead = else myNumBytesToRead =
a chunk to read - gBytesTransferred > kDataBufferSize) kDataBufferSize; gBytesToTransfer - gBytesTransferred;
myWide, lo = gBytesTransferred; myWide.hi = O;
R66
Chapter 9 Somewhere I'll Find You
/ / read from the current offset
/ / schedule a read operation Dat aHReadAsync ( gDat aReader, theRequest, myNumBytesToRead, &myWide, gReadDataHCompIet i onUPP, myNumBytesToRead) ;
/ / the data buffer
} else { / / we've transferred all the data gDoneTransferring = true;
}
As you can see, we first update the global variable gBytesTransferred that keeps track of the n u m b e r of bytes already transferred. Then we figure out how m a n y bytes remain to be read from the remote file; we read that number of bytes, if it's less than the size of our intermediate buffer, or else we read an entire buffer of data. Finally, we call DataHReadAsync to schedule a read operation. Notice that we specify the gReadDataHCompletionUPP as the read completion function. Once some data is read into the local buffer, our read completion function (Listing 9.11)will be executed. It's even simpler than the write completion function; all it does is schedule a write operation to copy the data from the buffer into the local file.
Listing 9.11
Responding to a read operation.
PASCAL_RTN void QTDR_ReadDataCompletionProc (Ptr theRequest, long theRefCon, OSErr theErr)
{
#pragma unused(theErr) / / we just finished reading some data, DataHWri te (gDataWri ter, theRequest, gBytesTransferred, theRefCon, gWri teDataHComplet i onUPP, theRefCon) ;
so schedule a write operation / / the data buffer / / write from the current offset / / the number of bytes to write
In this case, theRefCon contains the n u m b e r of bytes just read from the remote file, which is the n u m b e r of bytes that should be written to the local
File Transfer
267
file. Notice that now we specify gWriteDataHCompletionUPP as the write completion function. The read and write completion functions keep scheduling write and read requests, specifying each other as the completion function for those requests. So we keep successively reading and writing data, until the entire file is transferred.
Tasking the Data Handlers There is one final step needed to make this all work. Namely, we need to give the data handlers some processor time to do their work. We do this by periodically calling DataHTask. On the Macintosh, we can insert calls to DataHTask into the application function QTApp_Hand]eEvent, which is called by our application framework every trip through the main event loop. Listing 9.12 shows the definition of QTApp_Hand]eEvent in QTDataRef. Listing 9.12 Taskingthe data handlers. Boolean QTApp_HandleEvent (EventRecord *theEvent)
{
#pragma unused(theEvent) / / i f we're done, close down the data handlers i f (gDoneTransferring) QTDR_CloseDownHandlers () ; / / give the data handlers some time, i f they are s t i l l active i f (gDataReader != NULL) DataHTask(gDataReader) ; i f (gDataWriter l= NULL) DataHTask(gDataWri ter) ; return(false);
When the file is done being transferred, then QTApp_HandleEvent calls the function QTDR_CloseDownHandlers (defined later) to close things down. Otherwise, it calls DataHTask on both the URL data handler and the file data handler. At most one of them will have some work to do, but it doesn't hurt to task both of them. Our Windows framework does not, however, call QTApp_HandleEvent periodically, so we'll have to do that ourselves. Probably the easiest way is to install a timer task, like this" gTimerlD : SetTimer(NULL, O, kQTDR_TimeOut, (TIMERPROC)QTDR_TimerProc);
268
Chapter9 Somewhere I'll Find You
The timer callback function QTDR_TimerProc, defined in Listing 9.13, simply calls QTApp_HandleEvent.
Listing 9.13 Handling timer callbacks. void CALLBACKQTDR_TimerProc (HWNDtheWnd, UINT theMessage, UINT_PTR theID, DWORDtheTime)
{
#pragma unused(theWnd, theMessage, theID, theTime) QTApp_HandleEvent(NULL);
}
We need to remove the timer task once the data transfer is completed (as accomplished in Listing 9.14). It's important to know that a data handler might not execute our requests to read and write data asynchronously, even if we specify completion functions. If the handler decides to operate synchronously, then it will not return immediately when we call DataHReadAsync or DataHWrite; instead, it will perform the requested operation and then return. We still need to call DataHTask, however, to give the data handlers an opportunity to execute their completion functions.
Finishing Up When the write completion function QTDR_WriteDataCompletionProc determines that all the data has been read from the remote file and written into the local file, it sets the global variable gDoneTransferring to true. When OTApp_HandleEvent is called and gDoneTransferring is true, QTApp_HandleEvent calls QTDR_CloseDownHandlers, defined in Listing 9.14. Listing 9.14 Closing down the data handlers.
void QTDR_CloseDownHandlers (void)
(
i f (gDataReader l= NULL) { DataHCloseForRead(gDataReader) ; Cl oseComponent(gDataReader) ; gDataReader = NULL;
}
i f (gDataWriter l: NULL) { DataHCloseForWri te (gDataWri ter) ; Cl oseComponent(gDataWri ter) ; gDataWri ter = NULL;
}
File Transfer 269
/ / dispose of the data buffer i f (gDataBuffer != NULL) Di sposePtr (gDataBuffer) ; / / dispose of the routine descriptors i f (gReadDataHCompletionUPP ! = NULL) Di sposeDataHCompI et i onUPP(gReadDataHCompIet i onUPP) ; i f (gWriteDataHCompletionUPP ! = NULL) Di sposeDataHCompleti onUPP(gWri teDataHComp]eti onUPP) ; gDoneTransferri ng = false; #if TARGETOS WIN32 / / k i l l the timer that tasks the data handlers KilITimer(NULL, gTimerID) ; #endi f B
}
QTDR_CloseDownHandlers simply doses the connections to the ]oca| and
remote files and then closes the component instances On Windows, it also removes the timer task that was Event periodically. Listing 9.15 contains the complete definition of the ToLoca] Fi ] e function, which is called in response to the m e n u item.
Listing
9.15
os the data handlers. calling QTApp_HandleQTOR_CopyRemoteFileTransfer Remote File
Copying a remote file into a local file.
OSErr QTDR_CopyRemoteFileToLocalFile (char *theURL, FSSpecPtr theFile)
(
Handle Handle ComponentResult
myReaderRef = NULL; myWriterRef = NULL; myErr = badComponentType;
/ / data ref for the remote f i l e / / data ref for the local f i l e
/ / delete the target local f i l e , i f i t already exists; / / i f i t doesn't exist yet, we'll get an error (fnfErr), which we just ignore FSpDelete (theFi le) ; / / create the local f i l e with the desired type and creator myErr = FSpCreate(theFile, kTransFileCreator, kTransFileType, smSystemScript); i f (myErr ! = noErr) goto bai I ;
270
Chapter 9 Somewhere I'll Find You
/ / create data references for the remote f i l e and the local f i l e myReaderRef = QTDR_MakeURLDataRef(theURL) ; i f (myReaderRef == NULL) goto bai I ; myWriterRef = QTDR_MakeFileDataRef(theFi le) ; i f (myWriterRef == NULL) goto bai I ; / / find and open the URL and f i l e data handlers gDataReader = OpenComponent(GetDataHandl er(myReaderRef, URLDataHandl erSubType, kDataHCanRead)) ; i f (gDataReader == NULL) goto bai I ; gDataWri ter = OpenComponent(GetDataHandl er(myWri terRef, rAl i asType, kDataHCanWrite)) ; i f (gDataWriter == NULL) goto bai I ; / / set the data reference for the URL data handler myErr = DataHSetDataRef(gDataReader, myReaderRef) ; i f (myErr ! = noErr) goto bai I ; / / set the data reference for the f i l e data handler myErr = DataHSetDataRef(gDataWriter, myWriterRef) ; i f (myErr I= noErr) goto bai I ; / / allocate a data buffer; the URL data handler copies data into this buffer, / / and the f i l e data handler copies data out of i t gDataBuffer = NewPtrClear(kDataBufferSize) ; myErr = MemError() ; i f (myErr ! = noErr) goto bai I ; / / open a read-only path to the remote data reference myErr = DataHOpenForRead(gDataReader) ; i f (myErr ! = noErr) goto bai I ; / / get the size of the remote f i l e myErr = DataHGetFileSize(gDataReader, &gBytesToTransfer) ; i f (myErr l= noErr) goto bai I ;
File Transfer
271
/ / open a write-only path to the local data reference myErr = DataHOpenForWrite(gDataWriter) ; i f (myErr l= noErr) goto bai I ; / / start reading and writing data gDoneTransferring = fal se; gBytesTransferred = OL; gReadDat aHCompIet i onUPP = NewDataHCompI et i onUPP(QTDR_ReadDataCompIet i onProc) ; gWri teDataHCompI et i onUPP = NewDataHCompIet i onUPP(QTDR_WriteDataCompIet i onProc) ; / / start retrieving the data; we do this by calling our own write completion routine, / / pretending that we've just successfully finished writing 0 bytes of data QTDR_WriteDataCompl eti onProc (gDataBuffer, OL, noErr) ; bail: / / i f we encountered any error, close the data handler components i f (myErr I= noErr) QTDR_CloseDownHandl ers () ; return((OSErr)myErr) ;
So we've managed to use QuickTime's data handlers to provide a generalpurpose network file transfer capability that operates asynchronously, allowing us to play movies or perform other operations while the transfer is under way. Of course, there are still some refinements we might add, such as alerting the user if he or she decides to quit the application while a file transfer is in progress. I'll leave these as exercises for the interested reader. Notice that we call the function DataHGetFileSize to determine the size of the remote file (which is, of course, the number of bytes we need to transfer). DataHGetFileSize may need to read through the entire remote file to determine its size, which can sometimes slow things down (since we're calling it synchronously). Some data handlers (but not all) support the DataHGetFileSizeAsync function, which allows us to get this information asynchronously. You might try experimenting with DataHGetFileSizeAsync to see if it improves performance in your particular situation. In that vein, you might be wondering: Sure, we can use QuickTime to transfer data across the net, but is it any good? What's the performance like? My preliminary (and admittedly unscientific) tests show that our code is in fact very good. In a few sample FTP transfers, QTDataRef consistently transferred files at least as fast as the latest version of a popular shareware
272
Chapter9 Somewhere I'll Find You
Internet file transfer application for the Mac. Moreover, with a movie playing continuously in the foreground, QTDataRef took only about 10% longer to transfer the file than it took with no movie playing. And don't forget that our code works on Mac OS 8 and 9, Windows, and Mac OS X!
D a t a R e f e r e n c e Extensions Consider now this question" if we pass a handle data reference to the function GetGraphicsImporterForOataRef, how does it figure out which graphics importer to open and return to us? Recall (from Chapter 4, "The Image") that when we pass a file specification record to GetGraphicsImporterForFile, it first inspects the Macintosh file type (on Mac OS) and then the filename extension of the specified file. If neither of these inspections reveals the type of image data in the file, GetGraphicsImporterForFile must then validate the file data (that is, look through the file data for clues to the image type). With a handle data reference, where there is no file type or fllename extension, only the validation step is possible. Unfortunately, validation is timeconsuming and, alas, not guaranteed to produce correct results. QuickTime 3.0 provided a preliminary solution to this problem by allowing us to attach a filename to the referring data of a handle data reference. (Let's call this a I~lenaming extension.} That is to say, a handle data reference is a handle to a 4-byte handle that is optionally followed by a Pascal string containing a fllename. Listing 9.16 defines the function QTDR_AddFilenamingExtension that attaches a filename to the referring data of a handle data reference. Listing 9.16 Appending a filename to some referring data. OSErr QTDR_AddFilenamingExtension (Handle theDataRef, StringPtr theFileName)
{
unsigned char OSErr
myChar = O; myErr = noErr;
i f (theFileName == NULL) myErr = PtrAndHand(&myChar, theDataRef, sizeof(myChar)) ; else myErr = PtrAndHand(theFileName, theDataRef, theFileName[O] + 1); return (myErr) ;
Data Reference Extensions 2 7 3
The filename can contain an extension that provides an indication of the kind of data that's in the data reference target. For instance, a filename of the form myImage.bmp indicates that the data consists of Windows bitmap data. For reasons that will become clear in a few moments, QTDR_AddFi]enamingExtension looks to see w h e t h e r theFileName parameter is NULL; if it is, QTDR_AddFi 1enami ngExtensi on appends a single byte whose value is O. QuickTime 4.0 provides a more complete solution to this problem by allowing us to create data reference extensions for handle data references. A data reference extension is a block of data that is appended to the referring data, in pretty m u c h the same way that we just appended a fllename to that data. The main difference is that, unlike the filenaming extension, a data reference extension is packaged as an atom, with an explicit type. QuickTime currently supports four kinds of data reference extensions, defined by these constants" enum { kDataRefExtensionChokeSpeed kDataRefExtensionMIMEType kDataRefExtensionMacOSFileType kDataRefExtensionlnitializationData
};
= = = =
FOURCHARCODE('chok'), FOURCHARCODE('mime'), FOURCHARCODE('ftyp'), FOURCHARCODE('data') n
A data reference extension of type kDataRefExtensionChokeSpeed can be
added to a URL data reference to specify a choke speed (which limits the data rate of a file streamed using HTTP streaming). The other three types can be added to a handle data reference to help identify the kind of data in the target of the data reference or to supply some initialization data to the data handler. If a data reference extension is present, then the filenaming extension must also be present. The filename can be O-length, however, in which case the filenaming extension consists only of a single byte whose value is O. Listing 9.17 shows how to add a Macintosh file type as a data reference extension.
Listing 9.17 Appending a file type data reference extension. OSErr QTDR_AddMacOSFileTypeDataRefExtension (Handle theDataRef, OSType theType)
{
unsigned l o n g OSType OSErr
myAtomHeader[2] ; myType; myErr = noErr;
myAtomHeader[O] : EndianU32 NtoB(sizeof(myAtomHeader) + sizeof(theType)); myAtomHeader[1] = EndianU32 NtoB(kDataRefExtensionMacOSFileType); D
274
Chapter 9 Somewhere I'll Find You
myType = EndianU32 NtoB(theType) ; m
myErr = PtrAndHand(myAtomHeader, theDataRef, sizeof(myAtomHeader)) ; i f (myErr == noErr) myErr = PtrAndHand(&myType, theDataRef, sizeof(myType)) ; return (myErr) ;
This code simply calls PtrAndHand to append an atom header to the referring data and then calls PtrAndHand again to append the file type (suitably converted to big-endian format). Another way to flag the type of data in a handle is by specifying a MIME type. MIME (for Multipurpose Internet Mail Extension) is a standard protocol for transmitting binary data across the Internet. A MIME type is a text string used in MIME transmissions to indicate the type of the data being transmitted. (For instance, the string "video/quicktime" is the MIME type of QuickTime movie files.) MIME types can also be used locally to indicate the type of a file or other collection of data. Movie importers and graphics importers will look for MIME type data reference extensions to help identify the type of data specified by a handle data reference. If you are building some movie or image data in memory, you can use the QTDR_AddMIMETypeDataRefExtension function, defined in Listing 9.18, to add a MIME type as a data reference extension. (Be sure to add a filenaming extension before adding a MIME type data reference extension.) Listing 9.18 Appending a MIME type data reference extension. OSErr QTDR_AddMIMETypeDataRefExtension (Handle theDataRef, StringPtr theMIMEType)
{
unsigned long OSErr if
myAtomHeader[2] ; myErr = noErr;
(theMIMEType == NULL) return (paramErr) ;
myAtomHeader[O] = EndianU32 NtoB(sizeof(myAtomHeader) + theMIMEType[O] + 1); myAtomHeader[1] = EndianU32 NtoB(kDataRefExtensionMIMEType) ; B
myErr = PtrAndHand(myAtomHeader, theDataRef, sizeof(myAtomHeader)) ; i f (myErr == noErr) myErr = PtrAndHand(theMIMEType, theDataRef, theMIMEType[O] + 1); return (myErr) ;
Data Reference Extensions 275
Conclusion As we've seen, QuickTime uses data references to find the data that it's supposed to handle. Data references can be e m b e d d e d in movie files or passed to Movie Toolbox and ICM functions. So w h e t h e r we're building movies or operating on them, understanding data references is crucial to doing any real work with QuickTime. Here we've learned how to w o r k with data references to create reference movie files, play movies from RAM, and open movies located remotely on the Internet. In the previous chapter, we also saw how to use data references to create shortcut movie files and e m b e d d e d movies. In future chapters, we'll work with data references as a normal part of our QuickTime programming. On the other hand, data handlers are normally transparent to applications. We can use them directly for certain special purposes, such as transferring remote files to the local machine. But normally the QuickTime APIs insulate us from having to work with them at all. Typically, we can accomplish what we need by handing the Movie Toolbox or ICM a data reference and letting it communicate with the appropriate data handler.
276
Chapter9 Somewhere I'll Find You
W o r d Is Out
Introduction W h e n QuickTime was first introduced, it was able to handle two types of media data: video and sound. Curiously, the very next media type added to QuickTime (in version 1.5) was text, or the written word. Part of the motivation for adding text media was to provide the sort of "text below the picture" that you see in movie subtitles or television closed captioning, as illustrated in Figure 10.1. Here, the text provides the words of a song, which can be useful to hearing-impaired or non-English-speaking users. Similarly, the text might provide the dialog of a play or a readable version of the narration. Of course, the text doesn't have to just mirror the voice part of an audio track; it can be any annotation that the movie creator deems useful for the viewer. The text you see in Figure 10.1 is not part of the video track; rather, it is stored in a text track (whose associated media is of type TextMedi aType). Typically the text track is situated below the video track (as in Figure 10.1), but in fact it can overlay part or all of the video track. In order for both the text and the underlying video to be visible, the background of the text track should be transparent or "keyed out"; the text is then called keyed text. Figure 10.2 shows some keyed text overlaying a video track. Keying can be computationally expensive, however, so keyed text is seen less often than below-the-video text. QuickTime provides the capability to search for a specific string of characters in a text track and to move the current movie time forward (or backward) to the next (or previous) occurrence of that string. In addition, the standard movie controller provides support for a special kind of text track called a chapter track. A chapter track is a text track that has been associated with some other track (often a video or sound track); w h e n a movie contains a chapter track, the movie controller will build, display, and handle a pop-up m e n u that contains the text in the various samples in that track. The pop-up
277
Figure 10.1
A movie containing a text track.
Figure 10.2 A movie containing a keyed text track.
278
Chapter 10 Word Is Out
menu appears (space permitting) in the controller bar. The various parts of the associated track are called the track's chapters. When the user chooses an item in the pop-up menu, the movie controller jumps to the start time of the selected chapter. Figure 10.3 shows our standard appearing-penguin movie with a chapter track that indicates the percentage of completion {both before and after the user clicks the pop-up menu). Notice that we've had to hide the step buttons in the controller bar to make room for the chapter popup menu. Notice also that the text track itself is not visible. The QuickTime Player application, introduced with QuickTime 3.0, employs a slightly different user interface for accessing a movie's chapters. As you can see in Figure 10.4, a QuickTime Player movie window replaces the pop-up menu with a set of Up and Down Arrow controls, which select the previous and next chapter. QuickTime 3.0 also included a Web browser plug-in that supports linked text. Linked text is contained in a hypertext reference track (usually shortened to HREF track), which is simply a text track that has a special name (to wit, HREFTrack) and contains some media samples that pick out URL links. If a text sample contains text of the form
,the QuickTime plug-in will load the specified URL in the frame containing the movie when the user clicks the movie box while that text sample is active. {Let's call this a clickable link.) If the text is in the form A,then the plug-in will load the specified URL automatically when that text sample becomes active. (Let's call this an
automatic link.)
Figure 10.3 A movie with a chapter track.
Introduction
279
Figure 10.4 The chapter controls in a QuickTime Player movie window.
QuickTime 4 added one more text-handling tool, the ability to attach wired actions to data in a text track. A wired action is some action {such as setting a movie's volume or its current time) that is initiated by some particular event. The events that can trigger wired actions include both user events like moving or clicking the mouse and movie controller events like loading movies or processing idle events from the operating system. We'll investigate wired actions at length in future chapters; for the moment, consider the movie shown in Figure 10.5. This movie contains only one track, a text track. The text track is configured so that clicking on the word "Apple" launches the user's default Web browser and loads the URL h t t p : / / ~w. appl e. corn; in addition, rolling the cursor over the word "Pixar" loads the URL h t t p : / / ~ . p i x a r . c o m / . (Let's call this wired text.) In this chapter, we're going to take a look at the most basic ways of handling text in QuickTime movies. After we take a brief detour to upgrade the code that adjusts our Edit menu, we'll uncover some ways in which our existing sample applications can already interact with text. It turns out that these applications can do a surprising amount of work with text tracks; indeed, they can even create text tracks, in spite of the fact that they contain
280
Chapter 10 Word Is Out
Figure 10.5 A text track with wired actions.
no text-specific code. So we'll spend a little bit of time to see how that's possible. Then we'll see how to create text tracks using the standard Movie Toolbox functions. We'll also learn how to search and edit text tracks. Toward the end of this chapter, we'll see how to create chapter tracks and HREF tracks. When all is said and done, we'll have at hand the essential tools that we need to create text tracks, keyed text, chapter tracks, and linked text. Figure 10.6 shows the Test menu of this chapter's sample application, named QTText.
T h e Edit M e n u Revisited Let's begin by considering our code for enabling and disabling items in the Edit menu. (This might appear to have nothing at all to do with text handling, but it is actually fairly germane to this topic. Trust me.) Currently, when the user clicks the menu bar to choose one of our application's menus, our application framework calls the OTFrame_AdjustMenus function. (In our Macintosh framework, this happens in response to a mouseDown event in the
The Edit Menu Revisited 281
Figure 10.6
The Test menu of QTText. i nMenuBar window part; in our Windows framework, this happens when the MDI frame window receives the WM_INITMENUcommand.) Listing 10.1 shows the code in QTFrame_AdjustMenus that adjusts the Edit menu.
Listing 10.1
Adjusting the Edit menu (original version).
# i f TARGET OS MAC myMenu = GetMenuHandle (kEdi tMenuResID) ; #endif i f (myMC ! = NULL) { long myFlags; I
I
MCGetControl lerlnfo(myMC, &myFlags) ; QTFrame_SetMenultemState(myMenu, IDM_EDITUNDO, myFlags & mclnfoUndoAvailable ? kEnableMenultem : kDisableMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCUT, myFlags & mclnfoCutAvailable ? kEnabl eMenultem 9kDi sabl eMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCOPY, myFlags & mclnfoCopyAvailable ? kEnableMenultem : kDisableMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITPASTE, myFlags & mclnfoPasteAvailable ? kEnableMenultem 9kDisableMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCLEAR, myFlags & mcInfoClearAvailable ? kEnableMenultem 9kDi sableMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITSELECTALL, myFlags & mclnfoEditingEnabled ? kEnabl eMenultem 9kDi sabl eMenultem) ;
282
Chapter 10 Word Is Out
QTFrame_SetMenuItemState(myMenu, IDM_EDITSELECTNONE,myFlags & mcInfoEditingEnabled ? kEnableMenultem : kDisableMenultem) ; } else { QTFrame_SetMenultemState(myMenu, IDM_EDITUNDO, kDi sabl eMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCUT, kDi sabl eMenuItem) ; QTFrame_SetMenuItemState(myMenu, IDM_EDITCOPY, kDi sabl eMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITPASTE, kDi sabl eMenuItem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCLEAR, kDi sabl eMenultem) ; QTFrame SetMenultemState(myMenu, IDM EDITSELECTALL, kDisableMenultem) ; QTFrame_SetMenuItemState(myMenu, IDM_EDITSELECTNONE, kDi sabl eMenultem) ;
There's nothing particularly complicated here: if there is no movie controller associated with the frontmost window or there is no frontmost window, then we disable all the items in the Edit menu (that's the el se portion). Otherwise, we call the MCfetControllerInfo function to determine the current status of the movie controller and its associated movie. MCfetControllerInfo returns a set of flags that indicate which editing operations currently make sense for the specified movie controller and its movie. For instance, if there is some data available for pasting and editing is enabled, then the mclnfoPasteAvailable flag is set in the 32-bit long integer returned by MCGetControl lerInfo. In this case, our application should enable the Paste menu item. Conversely, if either editing is disabled for the specified movie or there is nothing to paste, then that flag is clear. In that case, the Paste menu item should be disabled. We call the function QTFrame SetMenuItemState to enable or disable the Paste menu item, like this: QTFrame SetMenultemState(myMenu, IDM EDITPASTE, myFlags & mclnfoPasteAvailable ? kEnableMenultem
9kDisableMenultem);
We've already considered QTFrame_SetMenuItemState in Chapter 1, "It All Starts Today"; it just calls the appropriate platform-specific function for enabling or disabling a menu item.
Emulating QuickTime Player So far, so good. But there is a very important capability that we still need to add to our sample applications. If we launch the QuickTime Player application, open a movie, make a selection, and then hold down the Option key (or, on Windows, both the Ctrl and Alt keys) while clicking the Edit menu, we'll see something like the menu shown in Figure 10.7. Notice that the Paste menu item is now labeled "Add" and the Clear menu item is now labeled "Trim." Similarly, if we hold down just the Shift key while clicking
The Edit Menu Revisited 2 8 3
Figure 10.7 The Edit menu of QuickTime Player (Option key down).
Figure 10.8 The Edit menu of QuickTime Player (Shift key down). the Edit menu, we'll see the menu shown in Figure 10.8. Now the Paste menu item is labeled "Replace." Finally, if we hold down the Option and the Shift keys (or, on Windows, the Ctrl and Alt and Shift keys)while clicking the Edit menu, the Paste menu item will be labeled "Add Scaled," as shown in Figure 10.9. (For the moment, don't worry about what these renamed menu items actually do; we'll get to that in the next section.) What's happening here is that QuickTime Player is not using MCGetControl lerInfo to do its Edit menu adjusting, at least for the first five menu commands. Instead, it's using the MCSetUpEditMenu function, which is specially designed to change the Edit menu item labels in the ways just described, depending on which keyboard modifier keys the user is holding down. MCSetUpEditMenu is declared essentially like this: ComponentResul t MCSetUpEditMenu (MovieControl I er mc, 1ong modif i ers, MenuHandle mh) ; MCSetUpEditMenu correctly enables or disables and names the first five com-
mands in the Edit menu specified by the menu handle mh, as long as those items have the standard arrangement (Undo, a separator line, Cut, Copy, Paste, and Clear). It appears, then, that we can simplify our menu-adjusting code and gain the additional behaviors just described by using MCSetUpEditMenu ourselves.
284
Chapter l O Word ls Out
Figure 10.9 The Edit menu of QuickTime Player (Shift and Option keys down). There are just a couple of changes w e n e e d to m a k e to support MCSetUpEditMenu. Primarily, we n e e d to add a p a r a m e t e r to our QTFrame_AdjustMenus function so that w e can pass it the c u r r e n t k e y b o a r d modifiers. H e n c e f o r t h , QTFrame_AdjustMenus will be declared like this:
int QTFrame_AdjustMenus (WindowReference theWindow, MenuReference theMenu, long theModifiers) ; Getting the appropriate k e y b o a r d modifiers in our M a c i n t o s h code is easy. W h e n e v e r we call QTFrame AdjustMenus, either w e d o n ' t care about the moditiers (so we can pass OL) or we have an event record available (so we can pass
(long) t heEvent->modi fi ers).
Getting the M o d i f i e r Keys on W i n d o w s W h e n we call QTFrame AdjustMenus on W i n d o w s , however, we need to do u
some additional work to determine which (if any) modifier keys the user is holding down when clicking the Edit menu. Remember that we want to pass MCSetUpEditMenu a long integer whose bits indicate which modifier keys are active. The "gotcha" here is that these are supposed to be the modifier keys on a Macintosh keyboard. MCSetUpEditMenu knows nothing about the Alt or Ctr] keys found on Windows keyboards. Rather, it's expecting a 32-bit value in which the up or down state of the relevant modifier keys is encoded using these bits (defined in Events.h): enum { cmdKey shiftKey alphaLock optionKey
};
control Key
= = = =
1 1 1 1
<< << << <<
cmdKeyBit, shiftKeyBit, alphaLockBit, optionKeyBit,
= 1 << control KeyBit
// // // //
Ox0100 Ox0200 Ox0400 Ox0800
/ / OxlO00
The Edit Menu Revisited
285
For example, if only the Option key is down, the modifiers value should be 0x00000800. Similarly, if both the Shift and Control keys are down, the modifiers value should be 0x00001200. QuickTime maps the Windows modifier keys to the Macintosh modifier keys in this manner: 9 The Windows Alt key is mapped to the Macintosh Control key. 9 The Windows Ctrl key is mapped to the Macintosh Command key. 9 The Windows Shift key is mapped to the Macintosh Shift key. 9 The Windows Caps Lock key is mapped to the Macintosh Caps Lock key. 9 The combination of the Windows Alt and Ctrl keys is mapped to the Macintosh Option key. To help us construct a Mac-style modifiers long word, we'll add these constants and compiler macros to the file WinFramework, h" #define #define #define #define
VK MAC CONTROLKEY VK MAC COMMANDKEY VK MAC SHIFTKEY VK MAC CAPSKEY
VK MENU VK CONTROL VK SHIFT VK CAPITAL
#defi ne QTFrame_IsControl KeyDown(theKeyState) (theKeyState[VK_MAC_CONTROLKEY] & Ox80 ? i : O) #def i ne QTFrame_IsCommandKeyDown(t heKeyState) (theKeyState[VK_MAC_COMMANDKEY] & Ox80 ? 1 : O) #define QTFrame_IsShi f t KeyDown(theKeyState) (theKeyState[VK_MAC_SHIFTKEY] & OxSO ? I 9O) #defi ne QTFrame_IsAl phaLockKeyDown(theKeyState) (theKeyState[VK_MAC_CAPSKEY] & Ox80 ? I : O) #def i ne QTFrame_IsOpti onKeyDown( theKeyState) (QTFrame_IsControl KeyDown(theKeyState)) && (QTFrame IsCommandKeyDown(theKeyState))
\ \ \ \ \ \
m
On Windows, a key state array (represented by the argument theKeyState in these macros) is a 256-byte array that contains information about each of the 256 virtual-key codes. If a key is down, then the high-order bit (0x80) of the corresponding element of this array will be set. For instance, if the Alt key is down, then the high-order bit of the array element whose index is 0x12 will be set. (The virtual-key code for the Alt key is VK_MENU, which is defined as 0x12 in the file Winuser.h.) We can fill a key state array with the current values by calling the GetKeyboardState function. Then all we need to do is inspect the Windows modifier keys that are of interest to us and construct a Mac-style modifiers value that
286
Chapter 10 Word Is Out
encodes that information. W h e n we need to call OTFrame_AdjustMenus, we can get the current set of modifier keys by calling OTFrame_GetKeyboardModi f i e f s , defined in Listing 10.2.
Listing 10.2. Getting the Windows keyboard modifier keys. static long QTFrame_GetKeyboardModifiers (void)
{
l ong BYTE
myModifiers = OL; myKeyState[256] ;
i f (GetKeyboardState(&myKeyState[O])) { i f (QTFrame IsOptionKeyDown(myKeyState)) myModifiers I = optionKey; el se i f (QTFrame_IsCommandKeyDown(myKeyState)) myModifiers I = cmdKey; el se i f (QTFrame_IsControl KeyDown(myKeyState)) myModifiers I = controIKey; i f (QTFrame IsShiftKeyDown(myKeyState)) myModifiers I = shiftKey; i f (QTFrame_IsAlphaLockKeyDown(myKeyState)) myModifiers I = alphaLock; return (myModifi ers) ;
So, on Windows, we are now able to pass the correct set of modifier flags to MCSetUpEditMenu. But w h a t do we pass for the third parameter, w h i c h on Mac OS is a m e n u handle for the Edit menu? The answer, it turns out, is that we'll pass the value NULL. The reason for this is that on Windows, we access our m e n u s using a value of type HMENU,not MenuHand] e. This means, however, that on W i n d o w s we cannot d e p e n d on MCSetUpEditMenu to either highlight or r e n a m e the items in the Edit menu. For that, we'll have to write our o w n code.
R e n a m i n g t h e Edit M e n u I t e m s on W i n d o w s At this point, you might be w o n d e r i n g w h y w e ' r e bothering to call MCSetUpEdi tMenu on Windows, if it isn't going to help us with highlighting or renaming the items in the Edit menu. The a n s w e r is that MCSetUpEditMenu does more than simply enable or disable m e n u items and r e n a m e t h e m to m a t c h the state of the active modifier keys. MCSetUpEditMenu also sets some flags
The Edit Menu Revisited 287
maintained internally by the movie controller that affect the operation of subsequent editing commands. For instance, w h e n we call MCPaste, it looks at those flags to determine whether it should paste, replace, add, or add scaled. In other words, if we don't call MCSetUpEditMenu, all our editing operations will just be the default undo, cut, copy, paste, and clear operations. On Windows, we still have two tasks left to handle. First, we need to perform our own Edit menu item enabling and disabling. We already have code for this (see Listing 10.1 again), so we'll just conditionalize that code to be executed under Windows but not under Mac OS. Second, we need to find a way to rename the Edit menu items according to the current state of the modifier keys. This task is actually relatively easy, since QuickTime provides the MCGetMenuString function that we can use to retrieve the label for a particular menu item, given a set of modifier keys. Suppose, for instance, that we execute this line of code (here, myString is of type Str255): MCGetMenuString(myMC, optionKey, mcMenuPaste, myString);
If MCGetMenuString completes successfully, then myStri ng will hold the string "Add." All we need to do then is insert that string into our Windows Edit menu. The function QTFrame_ConvertMacToWinMenuItemLabel, defined in Listing 10.3, handles all of this for us. Listing 10.3
Renaming a Windows Edit menu item.
void QTFrame ConvertMacToWinMenultemLabel (MovieController theMC, MenuReference theWinMenu, long theModifiers, UInt16 theMenultem) Str255 char char char short
myString; *myLabeIText= NULL; *myBeginText= NULL; *myFinaIText = NULL; myLabelSize= O;
/ / get the appropriate label for the specified item and keyboard modifiers MCGetMenuString(theMC, theModifiers, MENU ITEM(theMenultem), myString); switch (theMenultem) { case IDM EDITUNDO: myBeginText = kAmpersandText; myFinaIText = kWinUndoAccelerator; break; case IDM EDITPASTE. myBegi nText = ""; myFinaIText = kWinPasteAccelerator;
288
Chapter 10 Word Is Out
break; case IDM EDITCLEAR: myBeginText = kAmpersandText; myFinaIText = kWinClearAccelerator; break; default: / / currently, only the Undo, Paste, and Clear items are modified by / / MCSetUpEditMenu, so that's all we'll handle here return; myLabelSize = strlen(myBeginText) + myString[O] + strlen(myFinaIText) + 1; myLabeIText = malloc(myLabeISize) ; i f (myLabeIText == NULL) return; BlockMove(myBeginText, myLabeIText, strlen(myBeginText)) ; BlockMove(&myString[1], myLabeIText + strlen(myBeginText), myString[O]) ; BlockMove(myFinaIText, myLabeIText + strlen(myBeginText) + myString[O], strl en (myFinal Text) ) ; myLabeIText[myLabeISize- 1] = ' \ 0 ' ; QTFrame SetMenultemLabel (theWi nMenu, theMenultem, myLabelText) ; free (myLabelText) ;
QTFrame_ConvertMacToWinMenultemLabel also adds the ampersand (&) to the beginning of several of the Edit m e n u items (so that the first letter is underlined) and the appropriate keyboard accelerator label to the end of all of them.
Putting It All Together We're finally ready to put all these pieces together. Listing 10.4 shows our revised version of Listing 10.1. W h e n no movie controller is available, we disable all the Edit m e n u items in exactly the same m a n n e r we did in our earlier version. And for the Select All and Select None items, we call MCfietControllerlnfo and QTFrame_SetMenultemState, just like before. But for the five standard Edit m e n u commands, we now call MCSetUpEditMenu on both Mac and Windows. In addition, on Windows we need to do all m e n u item enabling and disabling ourselves, and we need to update the m e n u item labels, using our function QTFrame_ConvertMacToWinMenuItemLabel.
The Edit Menu Revisited 2 8 9
Listing 10.4 Adjusting the Edit menu (revised version). # i f TARGET OS MAC myMenu = GetMenuHandle(kEdi tMenuResID) ; #endif i f (myMC == NULL) { / / i f there is no movie control ler, disable all the Edit menu items QTFrame_SetMenuItemState (myMenu , IDM EDITUNDO, kDisableMenultem) ; QTFrame SetMenultemState(myMenu, IDM EDITCUT, kDisableMenultem); QTFrame SetMenultemState(myMenu, IDM EDITCOPY, kDisableMenuItem); QTFrame SetMenultemState(myMenu, IDM EDITPASTE, kDisableMenultem); QTFrame_SetMenuItemSta te (myMenu , IDM EDITCLEAR, kDisableMenultem); QTFrame_SetMenuItemSta te (myMenu , IDM EDITSELECTALL, kDisableMenuItem) ; QTFrame_SetMenuItemSta te (myMenu , IDM EDITSELECTNONE, kDisableMenultem); else { MCGetControl lerlnfo(myMC, &myFlags) ; D
QTFrame_SetMenultemState(myMenu, IDM_EDITSELECTALL, myFlags & mclnfoEditingEnabled ? kEnabl eMenultem 9kDi sabl eMenultem) ; QTFrame_SetMenuItemState(myMenu, IDM_EDITSELECTNONE, myFlags & mcInfoEditingEnabled ? kEnabl eMenuItem 9kDi sabl eMenuItem) ; # i f TARGET OS MAC MCSetUpEditMenu(myMC, theModi fiers, myMenu); #endif # i f TARGET OS WIN32 MCSetUpEditMenu(myMC, theModifi ers, NULL); QTFrame_SetMenultemState(myMenu, IDM_EDITUNDO, myFlags & mclnfoUndoAvailable ? kEnableMenultem : kDisableMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCUT, myFlags & mclnfoCutAvailable ? kEnableMenultem 9kDisableMenuItem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCOPY, myFlags & mclnfoCopyAvailable ? kEnableMenultem : kDisableMenultem) ; QTFrame SetMenultemState(myMenu, IDM EDITPASTE, myFlags & mclnfoPasteAvailable ? kEnableMenultem : kDisableMenultem) ; QTFrame_SetMenultemState(myMenu, IDM_EDITCLEAR, myFlags & mclnfoCl earAvai I abl e ? kEnableMenultem : kDisableMenultem) ; QTFrame_ConvertMacToWi nMenultemLabel (myMC, myMenu, theModifi ers, QTFrame_ConvertMacToWi nMenultemLabel (myMC, myMenu, theModi fiers, QTFrame_ConvertMacToWi nMenultemLabel (myMC, myMenu, theModif i e r s , QTFrame_ConvertMacToWinMenultemLabel (myMC, myMenu, theModifiers, QTFrame_ConvertMacToWinMenultemLabel (myMC, myMenu, theModifiers, #endi f
}
290
Chapter 10 Word Is Out
IDM_EDITUNDO); IDM_EDITCUT); IDM_EDITCOPY); IDM_EDITPASTE); IDM_EDITCLEAR);
There is one final modification that we need to make to our W i n d o w s source code. Apparently, on Windows calling the MCIsP]ayerEvent function has the nasty side effect of clearing the movie controller flags that store the current modifier key settings. So we need to make sure that we do not call MCIsPlayerEvent if we are about to execute an editing command. We can do this by adding the condition (theMessage != WM_COMMAND)in the movie window procedure QTFrame_MovieWndProc. See the version of WinFramework.c included in this chapter's code for the exact placement of this fix.
Text importing Suppose now that we've implemented all the changes described in the previous section. Let's see what all this work has bought us.
Importing Text from the Clipboard Open a movie with a video track, perhaps even the penguin movie we created in Chapter 6, "Doug's 1st Movie." Select part or all of the movie. Then switch to some application that can handle text; in that application, select some text and copy it. Then return to our upgraded application and execute the Add Scaled c o m m a n d in the Edit m e n u (that is, choose Paste while holding down the Shift and Option keys on the Mac, or the Shift and Ctrl and Alt keys on Windows). Voile--we've just added a text track to our movie, positioned below the video track. Keep in mind that our upgraded sample applications contain absolutely no special code for handling text media. So how did we manage to create a text track so effortlessly? The answer is that MCPaste looks to see what kind of data it's being asked to insert into the open movie. If it's a segment of a movie, then MCPaste just inserts the data as w e ' d expect. But if the data isn't movie data, MCPaste looks around for a QuickTime component that can import that kind of data as a movie. In other words, MCPaste goes looking for a suitable movie import component. In this case, it finds the text movie import component (component type MovieImportType and subtype TextMediaType), which inspects the current modifier flags cached by the movie controller and performs the operation corresponding to those flags as summarized in the following list. If none of the relevant modifier flags is set, the text movie importer pastes the text data at the current position in the movie. If a text track already exists in the movie, the pasted text is inserted into that track and inherits all the spatial and visual characteristics of that track. But if no text track exists in the movie, the text movie importer creates a new track that has
Text Importing 291
the same size and position as the current movie box. The pasted text is given a default duration of two seconds. [] If only the Shift modifier flag is set, then MCPaste performs a Replace operation. If the movie has a non-empty selection, the pasted text replaces the c u r r e n t selection; otherwise, if there is no selection, the p a s t e d text replaces the entire movie. In both cases, the duration of the pasted text sample is the default two seconds. 9 If
only the Option modifier flag is set, then MCPaste performs an Add operation: the text track is positioned below the existing video track, with a height that accommodates the pasted text (this is called adding in parallel). The duration of the pasted text sample is the default two seconds.
9 If both the Shift modifier flag and the Option modifier flag are set, then MCPaste performs an Add Scaled operation: a text track is added in parallel for the duration of the current selection. If there is no selection, then the text track is added in parallel for the duration of the entire movie. On Macintosh operating systems only, holding down the Control key and any other combination of modifier keys while choosing Paste in the Edit menu causes the text movie importer to display the Text Import Settings dialog box, shown in Figure 10.10. This dialog box allows the user to configure some settings of the pasted text.
I m p o r t i n g T e x t f r o m a File The text movie importer can also import text stored in a file and, indeed, provides some additional capabilities that are not available w h e n pasting text from the scrap. If we open a text file using any of our sample applications, the text importer creates a movie that has a text sample for every paragraph of text in the file. Each text sample will have the standard default duration of two seconds and will be drawn in the default text font, which is dependent upon the operating system. Note that, since we're importing a file and not pasting data from the system scrap, our existing sample applications will exhibit this behavior, whether or not we've applied the changes described in the previous section. This is just another case of NewMovieFromFile detecting that the file we've asked it to process is not a QuickTime movie file and then looking around for a suitable movie importer to handle that data. (See Chapter 4, "The Image," for more details on this.) The text importer recognizes a large number of text descriptors that modify the default characteristics of the imported text. Suppose that we open a text file that contains these lines of text:
292
Chapter 10 Word Is Out
Figure 10.10 The Text Import Settings dialog box. (QTtext} { font :Tekton} {plain} { size: 18} {textColor: O, O, O}{backColor: 65535, 65535, O} {justify:center} {timeScal e:600} {width:240} {height:40} { t i meStamps:absolute } { language: 0} { text Encoding :0 } { shri nkTextBox: on} [00:00:00.000] {textBox: 10, O, 30, 240}We forgot to seed! [00:00:01.000] {textBox: 10, O, 30, 240}D'Oh! [00:00:01.100] {textBox: 10, 20, 30, 240}D'Oh! [00:00:01.200] {textBox: 10, 40, 30, 240}D'Oh! [00:00:01.300] {textBox: 10, 60, 30, 240}D'Oh! [00:00:01.400] {textBox: 10, 80, 30, 240}D'Oh! [00:00:01.500]
Text Importing
2931
Figure 10.11 The imported movie. The text importer inspects the text descriptors found within the braces and creates the movie whose first frame is shown in Figure 10.11. Unfortunately, we don't have space to investigate text descriptors in more detail here.
Text Tracks As we've seen, the text movie importer provides our applications with a good deal of text-handling power at a very small cost. In fact, we didn't have to do anything at all to allow our applications to import text files, and we simply had to upgrade our code for Edit menu item adjusting to allow them to handle pasted text. But we still need to see how to create text tracks directly, without relying on the text movie importer. After all, we want to be able to work with text data that's not read from a file or from the system scrap.
Adding Text Media Samples By this point in the book, programmatically adding a track to a movie should be old hat (since we've done this two or three times so far). We just need to call NewMovieIrack and NewIrackMedia to create a new track and media, call Begi nMedi aEdi ts to begin a media editing session, call AddMediaSample to add samples to the media, call EndMediaEdits to end the media editing session, and then call InsertMediaIntoIrack to insert the newly edited media into the track. For any new kind of media that we encounter, we really need to ask only two questions: What is the format of the data in the media samples? And, what is the structure of the sample description that we need to pass to AddMediaSample? For a text track, the media sample data is just the string of characters in the text itself, preceded by a 16-bit length field that specifies the n u m b e r of characters in that string. And the appropriate sample description is a text description structure, defined by the TextOescri pti on data type:
294
Chapter 10 Word Is Out
struct TextDescription { long long long short short l ong l ong RGBColor Rect ScrpSTElement char
};
descSize; dataFormat; resvdl; resvd2; dataReflndex; di spl ayFl ags; textJusti fi cati on; bgColor; defaul tTextBox; defaul tStyl e; defaul tFontName[1] ;
The fii"st five fields, of course, are the first five fields of the generic SampleDescription structure. The remaining fields are specific to text media. The displayFlags field holds a set of flags that indicate how the text is to be displayed. These flags allow us to specify various scrolling options and other positioning options. For the moment, we'll be content to specify just the dfClipToTextBox flag, which restricts any updates caused by changes in the text track to the area occupied by the text track. (By all means, however, you should experiment with some of the scrolling options, like dfScroll In and dfScrol 1Out.) The defaul tTextBox field specifies the location of the box that encloses the text. The rectangle is interpreted as relative to the upper-left corner of the text track rectangle. The t e x t J u s t i f i c a t i o n field contains a value that specifies how the text is to be justified within the text box. The Movie Toolbox recognizes these constants for specifying a text justification {defined in the header file TextEdit.h): enum {
};
teFlushDefault teCenter teFlushRight teFlushLeft
=0, =
1~
= -.1D =
-2
The bgColor field specifies the background color of the text box. The default text color is black. Note that because we call NewHandleClear to allocate a TextDescription structure, the default background color will also be black unless we change the values in the bgColor field. To make the text visible, we'll set the background color to white, like this:
Text Tracks 295
RGBColor
myBGColor = {Oxffff, Oxffff, O x f f f f } ;
(**mySampI eDesc), bgCoI or = myBGCoI or;
The last two fields of the TextDescription structure indicate the desired text style and font. We'll ignore these fields here. Listing 10.5 shows a segment of the QTText_AddTextTrack function, w h i c h we use to add a new text track to a movie. As you can see, it allocates a handle to a text description structure, fills in some of the fields with appropriate values, calls PtrToHand and PtrAndHand to create the text media sample, and then calls AddMediaSample to add the text media sample to the text media.
Listing 10.5 Adding a text media sample. TextDescri pt i onHandl e Handle UInt16 RGBColor
mySampleDesc = NULL; mySample = NULL; myLength; myBGColor = {Oxffff, Oxffff, O x f f f f } ;
mySampleDesc = (TextDescriptionHandle)NewHandleClear(sizeof(TextDescription)) ; i f (mySampleDesc == NULL) goto bai I ; (**mySampleDesc) .descSize = sizeof(TextDescription) ; (**mySampl eDesc), dataFormat = TextMedi aType; (**mySampleDesc) .displayFlags = dfCl ipToTextBox; (**mySampleDesc) .textJusti fication = teCenter; (**mySampl eDesc), defau I t TextBox = myBounds; (**mySampleDesc).bgColor = myBGColor; myLength = EndianU16_NtoB(mySampleText[O]) ; / / create the text media sample: a 16-bit length word followed by the text myErr = PtrToHand(&myLength, &mySample, sizeof(myLength)) ; i f (myErr == noErr) { myErr = PtrAndHand((Ptr) (&mySampleText[1]), mySample, mySampleText[O]) ; i f (myErr == noErr) AddMediaSample(myMedia, mySample, O, GetHandleSize(mySample), myTextSampl eDurati on, (SampleDescri pti onHandl e)mySampleDesc, 1, O, NULL); Di sposeHandl e (mySample) ; Di sposeHandl e ( (Handl e) mySampleDesc) ;
296
Chapter 10 Word Is Out
The Movie Toolbox also provides the TextMediaAddTextSample function, which allows us to simplify this process significantly. Indeed, all of the w o r k done in Listing 10.5 can be accomplished with this single line of code:
myErr = TextMediaAddTextSample( myHandler, (Ptr) (&mySampleText [i] ), mySampleText [0], O, O, O, NULL, NULL, teCenter, &myBounds, dfCl i pToTextBox, O, O, O, NULL, myTextSampleDurat i on, NULL); The function TextMediaAddTextSample takes 17 parameters (count 'em!), which is probably some kind of record for a Movie Toolbox function. The payoff for this complexity is that it allows us to dispense with allocating a sample description or a text sample and with worrying about endian issues. Instead, we pass it the text media handler, myHandler (which we can obtain by calling GetMedi aHandl er on the text media), the text, and a handful of other parameters describing the desired characteristics of the text track.
Positioning a Text Track When we create a text track, using either AddMediaSample or TextMediaAddTextSampl e, we need to specify the size and location of the text track. QTText determines the width of the new text track by calling GetTrackDimensions on the first video track in the movie"
GetTrackDimensions(myTypeTrack, &myWidth, &myHeight) ; QTText uses the constant kTextTrackHeight (defined as 20 pixels) as the height of the text track.
Text Tracks 297
For below-the-video text, we can specify the position of the text track by setting the track matrix, like this"
GetTrackMatrix(myTextTrack, &myMatrix) ; TranslateMatrix(&myMatrix, O, myHeight) ; SetTrackMatrix(myTextTrack, &myMatrix) ; All we've done here is translate the matrix d o w n w a r d by the height of the video track (myHeight). For text that overlays a video track, of course, we'll need to reset the matrix in some other way.
Enabling o r Disabling a T e x t T r a c k Each track in a QuickTime movie is either enabled or disabled. By default, a newly created track is enabled, in which case its media data directly contributes to the overall user experience. For example, an enabled video track is visible (unless of course it's completely covered by other enabled tracks}, and an enabled audio track is audible. Most other media types, including text media, are visual media types, so once again being enabled means being visible. On the flip side, a disabled track does not usually contribute audible or visible data to the movie. Disabling a track is a quick and easy way to hide or mute it. We can enable or disable a track by calling the SetTrackEnabled function, passing it a track identifier and a Boolean value that indicates w h e t h e r to enable {true) or disable (false) the specified track. When we create a text track, we make sure it's visible by enabling it, like this:
SetTrackEnabled(myTextTrack, true) ; We can hide the text track by passing fa] se to disable it. Even if a text track is disabled, however, it can still be of use in a movie. For instance, we can search for text in a disabled text track, and the movie controller scans all text tracks, including disabled ones, w h e n looking for chapter tracks. Similarly, the QuickTime plug-in searches all text tracks, even disabled ones, w h e n looking for an HREF track. Indeed, chapter tracks and HREF tracks are usually disabled.
Creating a T e x t T r a c k Listing 10.6 shows our complete function QTText_AddTextTrack for adding a text track to a movie. The parameter theStrings is an array of C strings; each element of that array is the text for a specific text sample. The parameter
298
Chapter 10 Word Is Out
theFrames is an array of integers; each element of that array indicates h o w m a n y video frames a text sample is to span. The sum of all the values in theFrames should equal the total n u m b e r of frames in the video track. Finally, the i sChapterTrack parameter indicates w h e t h e r the new text track is to be a chapter track; if i sChapterTrack is true, then the new text track is attached as a chapter track to the first track whose type is specified by the theType parameter.
Listing 10.6 Adding a text track. Track QTText_AddTextTrack (Movie theMovie, char *theStrings[], short theFrames[], short theNumFrames, OSType theType, Boolean isChapterTrack) Track Track Media MediaHandler Ti meScaI e Matri xRecord Fixed Fixed OSErr
myTypeTrack = NULL; myTextTrack = NULL; myMedia = NULL; myHandler = NULL; myTi meScaI e; myMatri x; myWidth; myHeight; myErr = noErr;
/ / get the ( f i r s t ) track of the specified type; / / this track determines the width of the new text track / / and ( i f i sChapterTrack is true) is the target of the new chapter track myTypeTrack = GetMovieIndTrackType(theMovie, 1, theType, movieTrackMediaType); i f (myTypeTrack == NULL) goto bai I ; / / get the dimensions of the target track GetTrackDimensions(myTypeTrack, &myWidth, &myHeight) ; myTimeScale = GetMediaTimeScale(GetTrackMedia(myTypeTrack)) ; / / create the text track and media myTextTrack = NewMovieTrack(theMovie, myWidth, FixRatio(kTextTrackHeight, 1), kNoVolume) ; i f (myTextTrack == NULL) goto bai I ; myMedia = NewTrackMedia(myTextTrack, TextMediaType, myTimeScale, NULL, 0); i f (myMedia == NULL) goto bai I ;
Text Tracks 2 9 9
myHandler = GetMediaHandler(myMedia) ; i f (myHandler == NULL) goto bai I ; / / figure out the text track geometry GetTrackMatrix(myTextTrack, &myMatrix) ; TranslateMatrix(&myMatrix, O, myHeight) ; SetTrackMatrix(myTextTrack, &myMatrix) ; SetTrackEnabled(myTextTrack, true) ; / / edit the track media myErr = Begi nMediaEdi ts (myMedia) ; i f (myErr == noErr) { Rect myBounds; short mylndex; TimeVal ue myTypeSampl eDurati on; TimeRecord myTimeRec; myBounds, top = O; myBounds, l e f t = O; myBounds.right = Fix2Long(myWidth) ; myBounds.bottom = Fix2Long(myHeight) ; / / determine the duration of a sample in the track of the specified type myTypeSampleDuration = QTUti I s GetFrameDuration(myTypeTrack) ; for (mylndex = O; mylndex < theNumFrames; mylndex++) { TimeVaI ue myTextSampI eDurat i on; Str255 mySampleText; myTextSampleDuration = myTypeSampleDuration * theFrames[mylndex] ; / / set the time scale of the media to that of the movie myTimeRec.value.lo = myTextSampleDuration; myTi meRec,value, hi = 0; myTimeRec.scale = GetMovieTimeScale(theMovie) ; ConvertTimeScale(&myTimeRec, GetMediaTimeScale(myMedia)) ; myTextSampleDuration = myTimeRec.value.lo; QTText_CopyCStringToPascal (theStrings[mylndex], mySampleText) ; / / Listing 10.5 omitted at this point, for space reasons
300
Chapter l O Word ls Out
}
}
/ / write out the new data to the media myErr = TextMediaAddTextSample( myHandler, (Ptr) (&mySampleText [1] ), mySampleText [0], O, O, O, NULL, NULL, teCenter, &myBounds, dfCl i pToTextBox, O, O, O, NULL, myTextSampleDurati on, NULL);
myErr = EndMediaEdi ts (myMedia) ; i f (myErr l= noErr) goto bai I ; / / insert the text media into the text track myErr = InsertMedialntoTrack(myTextTrack, O, O, GetMediaDuration(myMedia), fixed1); i f (myErr l= noErr) goto bai I ; / / set the text-handling procedure TextMedi aSetTextProc (myHandler, gTextProcUPP, (long) QTFrame_GetWindowObject FromFrontWi ndow() ) ; / / set the new text track as a chapter track for the track of the specified type i f (i sChapterTrack) AddTrackReference(myTypeTrack, myTextTrack, kTrackReferenceChapterList, NULL); bail: return (myTextTrack) ;
}
For the m o m e n t , you can ignore the calls to TextMediaSetTextProc and AddTrackReference. I'll explain t h e m a little later.
Text Tracks 301
Text Searching The Movie Toolbox provides several functions that we can use to search for a specific word or series of words in a text track. If we are interested in simply finding out where in a text track the next occurrence of a string is located, we can use the TextMediaFindNextText function, like this: myTimeValue = GetMovieTime(myMovie, NULL) ; myErr = TextMedi aFi ndNextText (myHandl er, (Ptr) (&theText [ I ] ) , theText [ 0 ] , myFlags, myTimeVal ue, &myFoundTime, &myFoundDur a t i on, &gOffset) ;
The first parameter, myHandler, is the text media handler associated with the text track. The second and third parameters specify the text to be searched for and the length of that text; here we're supposing that the text is contained in the variable theText, which is a Pascal string. The fourth parameter is a set of search flags, which indicate how TextMediaFindNextText is to search for the specified text. These flags are defined: enum { findTextEdgeOK findTextCaseSensitive findTextReverseSearch findTextWrapAround
= = = =
1 1 1 1
<< << << <<
O, 1, 2, 3,
findTextUseOffset
= 1 << 4
These constants are pretty m u c h self-explanatory, except for the first and the last. If findTextEdgeOK is set in the search flags, then TextMediaFindNextText will match text beginning at the movie time specified by the fifth parameter; otherwise, the text must occur in some later {or earlier, if findTextReverseSearch is set} sample. If findTextUseOffset is set, then TextMedi aFindNextText will search beginning at the offset specified by the last parameter. This allows us to find separate occurrences of the search text in a single text sample. Our QTText sample application maintains a couple of global variables that keep track of the kind of search the user wants to perform. We'll use those variables to set our search flags, like this:
302
Chapter 10 Word Is Out
myFl ags = findTextUseOffset; i f (!gSearchForward) myFlags [= findTextReverseSearch; i f (gSearchWrap) myFlags [= findTextWrapAround; i f (gSearchWithCase) myFlags [= findTextCaseSensitive;
If TextMediaFindNextText finds the text specified by the second and third parameters in some text sample, it returns the movie time of the beginning of that sample in the sixth parameter (here, &myFoundTime). It also returns the duration of that sample in the seventh parameter and, in the last parameter, the byte offset (from the beginning of the text portion of that sample) of the first character of that text. ~ i c a l l y , we don't just want to find out where some text begins; we also want to advance the movie to that point and highlight the found text. We can use the MCDoAction function with the mcActionGoToTime action to set the current movie time to the time returned to us by TextMediaFindNextText, like $0"
myNewTime,value, hi = O; myNewTime.value.lo = myFoundTime; myNewTime.scale = GetMovieTimeScale(myMovie) ; myNewTime,base = NULL; MCDoAction(myMC, mcActionGoToTime, &myNewTime);
And we can use the TextMediaHiliteTextSample function to highlight the selected text: myColor.red = myColor.green = myColor.blue = Ox8000; TextMediaHiliteTextSample(myHandler, myFoundTime, gOffset, gOffset + theText[O], &myColor);
/ / gray
Once again, however, the Movie Toolbox provides a function that greatly simplifies our work here. The MovieSearchText function, introduced in QuickTime version 2.0, finds the text, sets the movie time to the beginning of the text sample containing that text, and highlights the found text in that sample. So we can replace all the code we've encountered so far in this section with this single line of code:
Text Searching 303
myErr = MovieSearchText (myMovie, (Ptr) (&theText I l l ),
theText [0], myF1ags, NULL, ~myTimeVal ue, &gOffset) ;
W h e n we call MovieSearchText, we pass in the movie to search, the search text and search text length, a set of flags, the first text track to search, and the movie time at which to start the search. The set of flags can include any of the search flags just listed, as well as any of these additional flags that are specific to the MovieSearchText function: enum { search Text DontGoToFoundTi me searchTextDontHi I i teFoundText searchTextOneTrackOnl y searchText EnabI edTrac ksOnI y
};
= 1L << 1 6 , = 1L << 1 7 , = 1L << 1 8 , = 1L << 19
Including either of the first two flags allows us to override the default go-toand-highlight behavior of MovieSearchText. The next two flags modify the track-searching behavior. If we pass a track identifier in the fifth parameter, then MovieSearchText will search only that track if the searchTextOneTrackOnl y flag is set; otherwise, it will search all text tracks in the specified movie, starting with that track. We can restrict the search to all enabled text tracks by setting the searchTextEnabledTracksOnly flag. If MovieSearchText finds the specified text, it returns the movie time of the text sample in which the text was found and the byte offset within that sample of the found text. It also returns the track identifier of the track containing the text sample, unless the track parameter was set to NULLon input. Listing 10.7 contains the definition of our function QTText_FindText, which we use to search for text. As you can see, it uses either the TextMedi aFindNextText function or the MovieSearchText function, depending on the value of the compiler flag USE_MOVIESEARCHTEXT.
Listing 10.7 Finding some text. void QTText_FindText (WindowObject theWindowObject, Str255 theText)
{
ApplicationDataHdl Movie MediaHandler
31t}4 Chapter 10 Word Is Out
myAppData = NULL; myMovie = NULL; myHandler = NULL;
MovieController 1ong TimeVal ue OSErr
myMC = NULL; myFl ags = OL; myTimeVal ue; myErr = noErr;
myAppData = (ApplicationDataHdl) QTFrame_GetAppDataFromWindowObject (theWi ndowObject ) ; i f (myAppData == NULL) return; myMC = (**theWindowObject).fController; myMovie = (**theWindowObject).fMovie; myHandler = (**myAppData).fTextHandler; / / set the search features myFlags = findTextUseOffset; i f (!gSearchForward) myFlags I = findTextReverseSearch; i f (gSearchWrap) myFlags I = findTextWrapAround; i f (gSearchWithCase) myFlags I = findTextCaseSensitive; myTimeValue = GetMovieTime(myMovie, NULL); #if USE MOVIESEARCHTEXT myFlags I = searchTextEnabledTracksOnly; myErr = MovieSearchText(myMovie, (Ptr) (&theText[1]), theText[O], myFlags, NULL, &myTimeValue, &gOffset); i f (myErr != noErr) QTFrame_Beep(); / / i f the desired string wasn't found, beep #else i f (myHandler i= NULL) { TimeVal ue myFoundTime, myFoundDuration; TimeRecord myNewTime; RGBColor myColor; myColor.red = myColor.green = myColor.blue = Ox8000;// gray / / search for the specified text myErr = TextMediaFi ndNextText (myHandler, (Ptr)(&theText[1]), theText[Ol, myFlags, myTimeValue, &myFoundTime, &myFoundDuration, &gOffset); i f (myFoundTime ! = -1) { / / convert the TimeValue to a TimeRecord myNewTime.value.hi = O;
Text Searching 305
myNewTime.value.lo = myFoundTime; myNewTime.scale = GetMovieTimeScale(myMovie) ; myNewTime,base = NULL; / / go to the found text MCDoAction(myMC, mcActionGoToTime, &myNewTime); / / highlight the text TextMedi aHi I i teTextSampl e (myHandler, myFoundTime, gOffset, gOffset + theText[O], &myColor); } else { QTFrame_Beep() ;
}
}
/ / i f the desired string wasn't found, beep
#endif / / update the current offset, i f we're searching forward i f (gSearchForward && (myErr == noErr)) gOffset += theText[O] ;
Of course, your code w o n ' t need to use this compiler flag; you'll call just MovieSearchText or TextMediaFindNextText for your text searching. Here we simply want to illustrate how to call both of these functions.
Text Editing Let's consider now how to edit the data in a text track. Conceptually, this is a fairly simple operation. We can just call DeleteTrackSegment to delete one or more existing text samples from a track; then we can call TextMediaAddTextSample to add a new text sample to the text media and then InsertMediaIntoTrack to place that text sample at the desired location in the track. For the moment, we'll limit ourselves to replacing a single existing text sample with another sample that occupies the same location in the track (that is, one that has the same starting point and duration as the original sample). W h e n the user selects the Edit Current Text m e n u item, we'll display the dialog box shown in Figure 10.12. If the user clicks the OK button, we'll retrieve the text from the edit text control in that dialog box and use that text as the replacement text data. There are only two things we still need to figure out: How can we get the text of the current text sample (to put into the dialog box w h e n it's first displayed)? And, how can we determine the starting time and duration of the current text sample? Let's take these tasks in order.
306
Chapter 10 Word Is Out
Figure 10.12 The Edit Text dialog box.
Getting the Current Text The first task is the easier of the two, mainly because whenever the text media handler is about to display a new text sample, it calls an applicationdefined text callback procedure that we've previously installed by calling TextMediaSetTextProc {see Listing 10.6). The text callback procedure is passed several parameters, one of which is a handle to the sample data of the current media sample. So all we need to do is make a copy of the sample text in a place where we can find it w h e n we are about to display the dialog box shown in Figure 10.12. Listing 10.8 shows our application's text callback procedure.
Listing 10.8 Getting the current text. PASCAL_RTN OSErr QTText_TextProc (Handle theText, Movie theMovie, short *theDisplayFlag, long theRefCon)
{
#pragma unused(theMovie, theRefCon) char *myTextPtr = NULL; short myTextSi ze; short myIndex; / / on entry to this function, theText is a handle to the text sample data, / / which is a big-endian, 16-bit length word followed by the text i t s e l f myTextSize = EndianU16 BtoN(* (short *) (*theText)) ; myTextPtr - (char *) (*theText + sizeof(short)); / / copy the text into our global variable for (mylndex = 1; mylndex <= myTextSize; mylndex++, myTextPtr++) gSampleText [mylndex] = *myTextPtr; gSampleText [0] = myTextSize;
Text Editing
307
//
ask f o r the d e f a u l t t e x t d i s p l a y
*theDi spl ayFl ag = txtProcDefaul tDi splay; r e t u r n (noErr) ;
As you can see, we first parse the sample data to get the 16-bit length field and the location of the first character in the text string. Then we copy the characters into the global variable gSampleText, which is of type 5tr255. Finally, we return the value txtProcOefaultDisplay in the parameter theOisp] ayFl ag; this instructs the text media handler to use the display flags contained in the displayFlags field of the text description structure for that text sample. {There are also constants to force the sample to be shown or not shown, regardless of the media's default display flags.)
Finding Sample Boundaries Now we need to figure out how to find the starting time and duration of the current text media sample (so we k n o w what segment of the text track to replace). An easy way to get the starting time would be to call GetMovieTime in our text callback procedure and then assign the returned value to a global variable. A better way--because it can be used with media types other than text--is to call the GetTrackNextlnterestingTime function inside the OTText EditText function. GetTrackNextlnterestingTime allows us to search for specific times in a track, given a set of search criteria. The search criteria are specified by these flags: enum {
};
nextTimeMediaSample
= 1 << O,
nextTimeMediaEdit
= I << 1,
nextTimeTrackEdit
= 1 << 2,
nextTimeSyncSampl e
= 1 << 3,
nextTimeStep
= 1 << 4,
nextTimeEdgeOK
= I << 14,
nextTimelgnoreActiveSegment
= 1 << 15
For present purposes, we'll use the two flags nextTimeMediaSample and nextTimeEdgeOK, which tell GetTrackNextlnterestingTime to search in the next sample in the track's media but to consider samples that begin or end at the search starting time.
308
Chapter 10 Wordls Out
We'll begin by getting the current movie time {which might not be the beginning of the current text sample), like this: myMovieTime = GetMovieTime(myMovie, NULL);
Then we want to search backward to find the beginning of the current media sample: GetTrac kNext Interest i ngTime( myTrack, nextTimeEdgeOK [ nextTimeMediaSample, myMovieTime, -fixed1, &myI nteres t i ngTime, NULL) ;
The third parameter specifies the starting time for the search and the fourth parameter indicates the direction of the search; because the value here is negative, the search goes backward from the current movie time. Once GetTrackNextInterestingTime finds the beginning of the current media sample, it returns that time in the location pointed to by the fifth parameter. We've set the sixth parameter to NULLbecause we don't need the duration from the current time to the found interesting time to be returned to us. So we've found the beginning of the current text sample. We can find the duration of that sample by calling GetTrackNextInterestingTime once more, this time searching forward from the beginning of the sample, like this: myMovieTime = mylnteresti ngTime; GetTrac kNext I nteres t i ngTi me( myTrack, nextTimeEdgeOK I nextTimeMediaSample, myMovieTime, fixed1, NULL, &myDurati on) ;
In this case, we want only the duration of the sample returned to us, so we pass NULLin the fifth parameter and &myDuration in the sixth. Keep in mind that the time values that GetTrackNextInterestingTime returns to us are in the movie time scale. This is useful, since the parameters to DeleteTrackSegment must also be in the movie time scale. So we can now call DeleteTrackSegment to remove the current text sample from the track: myErr = DeleteTrackSegment(myTrack, mylnterestingTime, myDuration) ;
Text Editing 309
All that remains is to add a new text sample in place of the one we just removed. For this, we can call TextMediaAddTextSample as we did earlier. There is only one complication here: the duration we pass to TextMedi aAddTextSample must be expressed in the media time scale, not the movie time scale. But the Movie Toolbox conveniently provides the MediaTimeToSampleNum function that we can use to get the start time and duration of the c u r r e n t media sample in the media time scale, like this: myMovieTime = GetMovieTime(myMovie, NULL); myMediaCurrentTime = TrackTimeToMediaTime(myMovieTime, myTrack) ; MediaTi meToSampleNum( myMedi a, myMedi aCurrent Ti me, &myMedi aSampleIndex, &myMediaSampleStartTime, &myMediaSampleDurati on) ;
So we've got all the information we need to call TextMediaAddTextSample and InsertMedialntoTrack and thereby complete the text sample editing operation. For the complete definition of QTText_Edi tText, see the file QTText.c.
Chapter Tracks We learned earlier that a chapter track is just a text track that has been associated in a particular way with some other track. Let's call this other track the target track. We create the association between a text track and the target track by creating a track reference from that target to the text track. In general, a track reference is simply a way for one track to establish a relationship with some other track. The type of the track reference indicates the nature of that relationship. The Movie Toolbox currently provides three constants for track reference types: enum{ kTrackReferenceChapterLi st kTrackReferenceTimeCode kTrackReferenceModi fi er
};
= FOURCHARCODE('chap'), = FOURCHARCODE('tmcd'), = FOURCHAR CODE('ssrc')
A track reference of type kTrackReferenceChapterList is used to create a chapter track. A track reference of type kTrackReferenceTimeCode is used to create a timecode track, in which timecode values are associated with the samples of the target track. (We'll consider timecode tracks in more detail in
310
Chapter 10 Word Is Out
the next chapter.) A track reference of type kTrackReferenceModifier is used to create a modifier track; modifier tracks are useful w h e n you w a n t one track to modify the appearance or behavior of a target track. For instance, a tween track is a kind of modifier track that can be used to change, say, the volume of a sound track as the movie progresses. We'll encounter modifier tracks in several upcoming chapters, to change the current image of a sprite track and to apply a special effect to a video track. Other parts of QuickTime define additional types of track references. For example, the file Qui ckTimeVRFormat.h defines several types of track references that are used in building QuickTime VR movie files. It's actually a rather trivial operation to create a chapter track once we have a text track at hand. If myTypeTrack is a track identifier for a target track (in the present case, a video track), then we can create a chapter track reference to our text track like this:
AddTrackReference (myTypeTrack, myTextTrack, kTrackReferenceChapterList, NULL); The last p a r a m e t e r is a pointer to a long word in which AddTrackReference will return the index assigned to the new track reference; we don't need this information, so we set that p a r a m e t e r to NULL. All the chapter titles must be contained in a single text track; we specify the starting time for chapters w h e n we add the text to the text track by calling TextMedi aAddTextSample. Note that we need to create the chapter association only between the text track and one other target track, not b e t w e e n the text track and all other tracks in the movie. The target track must be enabled, but typically the chapter track is not enabled (unless we w a n t the text track to be visible). It's also very easy to remove a track reference and hence to change a chapter track back into a nonchapter text track. Again, if myTypeTrack is the target track, then we can disassociate it from the text track by calling DeleteTrackReference, like this:
DeleteTrackReference(myTypeTrack, kTrackReferenceChapterList, 1) ; Here the last p a r a m e t e r is the index of the track reference of the specified type that we want to remove. Our code attaches at most one chapter track to a target, so we can safely set that index to 1. Listing 10.9 shows our complete function for turning a text track into a chapter track or turning a chapter track back into a text track. The Boolean p a r a m e t e r i sChapterTrack determines w h e t h e r the first text track in the movie becomes a chapter track or is demoted from that lofty rank.
Chapter Tracks 311
Listing 10.9 Setting and unsetting chapter tracks. OSErr QTText_SetTextTrackAsChapterTrack (WindowObject theWindowObject, OSType theType, Boolean isChapterTrack)
{
ApplicationDataHdl Movie MovieController Track Track OSErr
myAppData= NULL; myMovie = NULL; myMC = NULL; myTypeTrack = NULL; myTextTrack = NULL; myErr = paramErr;
/ / get the movie, controller, and related stuff myAppData = (AppI i cat i onDataHd I ) QTFrame_GetAppData FromWindowObject (theWi ndowObject) ; i f (myAppData == NULL) return (myErr) ; myMovie = (**theWindowObject).fMovie; myMC = (**theWindowObject).fController; myTextTrack = (**myAppData).fTextTrack; i f ((myMovie I= NULL) && (myMC I= NULL)) { myTypeTrack = GetMovieIndTrackType(myMovie, 1, theType, movieTrackMediaType I movieTrackEnabledOnly) ; i f ((myTypeTrack l= NULL) && (myTextTrack I= NULL)) { / / add or delete a track reference, as determined by the desired final state i f (i sChapterTrack) myErr = AddTrackReference(myTypeTrack, myTextTrack, kTrackReferenceChapterList, NULL) ; else myErr = DeleteTrackReference(myTypeTrack, kTrackReferenceChapterList, 1) ; / / t e l l the movie controller we've changed aspects of the movie MCMovieChanged(myMC, myMovie) ; / / stamp the movie as d i r t y (**theWindowObject).flsDirty = true;
return (myErr) ;
312
Chapter 10 Word Is Out
Note that after we call AddTrackReference or DeleteTrackReference, we
need to call MCMovieChanged to inform the movie controller that w e ' v e changed the associated movie. This prompts the movie controller to redraw the movie controller bar to show or hide the chapter pop-up menu. The file QTText.c contains a n u m b e r of other chapter track utilities. Listing 10.10 defines the one we use for determining w h e t h e r a track is a chapter track; we call this function w h e n we need to determine w h e t h e r to place a check m a r k next to the Chapter Track m e n u item. Listing 10.10 Determining whether a track is a chapter track. Boolean QTText_IsChapterTrack (Track theTrack)
{
Movie Track long long long long
myMovie = NULL; myTrack = NULL; myTrackCount = OL; myTrRefCount = OL; myTracklndex; myTrReflndex;
myMovie = GetTrackMovie(theTrack) ; i f (myMovie == NULL) return(false); myTrackCount = GetMovieTrackCount (myMovie) ; for (myTracklndex = 1; myTracklndex <= myTrackCount; myTracklndex++) { myTrack = GetMovielndTrack(myMovie, myTracklndex) ; i f ((myTrack ! = NULL) && (myTrack ! = theTrack)) { / / i t e r a t e through all track references of type kTrackReferenceChapterList myTrRefCount = GetTrackReferenceCount (myTrack, kTrackReferenceChapterLi st) ; for (myTrReflndex = 1; myTrReflndex <= myTrRefCount; myTrRefIndex++) { Track myRefTrack= NULL; myRefTrack = GetTrackReference(myTrack, i f (myRefTrack == theTrack) return(true) ;
kTrackReferenceChapterList, myTrReflndex) ;
return(false);
Chapter Tracks 3 1 3
Hypertext Reference Tracks A hypertext reference track, or HREF track, is a text track in w h i c h some or all of the samples contain hypertext links, in the form of URLs. {Actually, there's no r e q u i r e m e n t that any of the samples in an HREF track contain a hypertext link, but in that case it's not very useful.} These URLs can be any kind of URL supported by QuickTime, including HTTP, HTTPS, FTP, file, RTSP, and JavaScript URLs. Indeed, if the QuickTime plug-in finds a URL it doesn't recognize, it passes it to the Web browser for processing. So, really, the sky's the limit in terms of the kind of URLs we can put in an HREF track. From a programming perspective, creating an HREF track is even easier than creating a chapter track. All we need to do is set the n a m e of a text track to "HREFTrack". The plug-in interprets the first text track in a movie having that name as the active HREF track. Listing 10.11 defines the function OTText_SetTextTrackAsHREFTrack that we can use to set and unset a text track as an HREF track.
Listing 10.11 Setting and unsetting HREFtracks. OSErr QTText_SetTextTrackAsHREFTrack (Track theTrack, Boolean isHREFTrack)
(
OSErr
myErr = noErr;
myErr = QTUtils SetTrackName(theTrack, i sHREFTrack ? kHREFTrackName 9kNonHREFTrackName); return (myErr) ;
A track's
name
is
stored
as
part
of
the
track's
user
data,
so
QTUti I s_SetTrackName (defined in QTUti I i t i es. c) calls SetUserDataltem to set the name. In QTText_SetTextTrackAsHREFTrack, we use these constants for the
track names: #define kHREFTrackName #define kNonHREFTrackName
"HREFTrack" "Text Track"
Ideally, each track should have a unique n a m e (though this is not required). So instead of hard-coding the name for the non-HREF track, we can generate a track n a m e dynamically, looking at the n a m e s that are already assigned to tracks in the movie. QTOtilities.c defines a function, OTUtils_MakeXrackNameByXype, that we can call to accomplish this. Reworking QTText_SetTextTrackAsHREFTrack to use QTUtils_MakeTrackNameByType is left as an exercise for the reader.
31/1 Chapter 10 Word Is Out
Occasionally, it's useful to know whether a specified text track is an HREF track. {For instance, QTText needs to know this to decide whether to put a check mark beside the HREF Track menu item.) The function QTText IsHREFTrack, defined in Listing 10.12, returns a Boolean value that indicates whether a given text track is an HREF track. Listing 10.12 Determining whether a track is an HREF track. Boolean QTText_IsHREFTrack (Track theTrack)
{
Boolean char
isHREFTrack = f a l s e ; *myTrackName = NULL;
myTrackName = QTUti I s GetTrackName(theTrack) ; i f (myTrackName ! = NULL) isHREFTrack = (strcmp(myTrackName, kHREFTrackName) == O) ; free (myTrackName) ; r e t u r n ( i sHREFTrack) ;
S o m e L o o s e Ends Let's finish up by taking care of a few loose ends in our basic application framework that become apparent when we start working with text tracks. As you know, when we paste some data into a movie, the current movie time is set to the time immediately following the pasted data. (This is the standard behavior with any kind of pasting.) If pasting causes the movie box to expand, it might happen that the expanded portion of the movie box in the current frame contains areas that should be erased but that are not erased by the movie controller. For example, if we've added some text in parallel, we might see something like Figure 10.13. Here, the video media handler has redrawn the video portion of the movie box, but the text media handler, thinking (correctly) that there's no text for the current movie time, has left the text portion of the movie box untouched. As a result, the image of the movie controller bar, which used to occupy the space now occupied by the text track, is not erased. This is not good, but it's easy enough to fix. When some part of the movie box needs to be redrawn, an update event is generated for that portion of the movie box. When we pass that event to MCIsPlayerEvent, the movie controller redraws the appropriate portion of the movie and clears that area from the update region of the window. The problem, as we've just seen, is that the movie controller doesn't think that the bottom portion needs to be redrawn and hence doesn't redraw it. We can solve this problem by erasing that portion of the window ourselves. Listing 10.13 shows our updated version of QTApp_Draw. Some Loose Ends 315
Figure 10.13 A movie window after adding in parallel. Listing 10.13 Redrawing a movie window. void QTApp_Draw (WindowReference theWindow) GrafPtr GrafPtr WindowPtr Rect
mySavedPort = NULL; myWindowPort = NULL; myWindow = NULL; myRect;
Get Port (&mySavedPort ) ; myWindowPort = QTFrame_GetPortFromWindowReference(theWi ndow) ; myWindow = QTFrame GetWindowFromWindowReference (theWi ndow) ; m
i f (myWindowPort == NULL) return; MacSetPort (myWindowPort) ; # i f TARGET API MAC CARBON GetPortBounds (myWindowPort, &myRect); #else myRect = myWindowPort->portRect; #endif
316
Chapter 10 Word Is Out
Begi nUpdate(myWindow) ; i f (QTFrame_IsDocWindow(theWindow)) EraseRect (&myRect) ; EndUpdate(myWindow) ; MacSetPort (mySavedPort) ;
As you can see, we call EraseRect on the entire window rectangle. Keep in mind, however, that BeginUpdate limits the redrawn portion to the intersection of the visible region of the window and the current update region. Since MCIsPlayerEvent will already have removed the active movie region from the update region, our call to EraseRect just redraws the visible portion of the update region that wasn't redrawn by the movie controller. The last thing we need to do is make sure that the entire movie box is included in the update region when we call MCIsPlayerEvent. We can accomplish this by adding a few lines to our QTFrame_HandleEditMenuItem function. Essentially, we need to make sure to invalidate the entire movie box whenever the size of the movie box might have changed. Listing 10.14 shows the lines we'll add to the end of QTFrame_HandleEdi tMenuItem.
Listing
10.14 Invalidating a movie window.
/ / i f the size of the movie might have changed, invalidate the entire movie box i f ((theMenultem == IDM_EDITUNDO) II (theMenultem == IDM_EDITCUT) II (theMenultem == IDM_EDITPASTE) II (theMenultem == IDM EDITCLEAR)) { Rect myRect; #if TARGET OS WIN32 RECT myWinRect; #endi f m
MCGetControl I erBoundsRect(myMC, &myRect); #if TARGET OS MAC Inval WindowRect(QTFrame_GetWindowFromWindowReference(theWi ndow), &myRect); #endif #if TARGET OS WIN32 QTFrame_ConvertMacToWinRect (&myRect, &myWinRect) ; InvalidateRect(theWindow, &myWinRect, false) ; #endif
}
Some Loose Ends 3 1 7
With these changes made, we should see no glitches like those in Figure 10.13.
Conclusion We've covered a fair a m o u n t of ground in this chapter. We've seen h o w to create text tracks, chapter tracks, and HREF tracks; w e ' v e also learned h o w to search a text track and edit the data in a text track. Along the way, w e ' v e seen how to upgrade our Edit m e n u item adjusting and our movie w i n d o w redrawing, so that even our applications that are not directly concerned w i t h text can import text from files or from the system scrap. We've also learned a more general lesson: QuickTime often provides more than one w a y to accomplish some particular task. We've seen, for instance, that we can call either AddMediaSampl e or TextMedi aAddTextSampl e to add media samples to a text track. And, we can call either TextMediaFindNextText or MovieSearchText to search for text within a text track. W h i c h of these functions we use in any particular case is a matter of taste, no doubt, but also a matter of simplicity and code size. TextMediaAddTextSample and MovieSearchText hold the clear advantage w h e n we consider the a m o u n t of source code we need to write and the kinds of details (like endian issues) to which we need to attend. In the future, we'll generally opt for the simpler, cleaner way of solving our p r o g r a m m i n g tasks (and leave the dinosaur bones for the archeologists).
318
Chapter 10 Word Is Out
Timecode
Introduction It's often useful--especially when editing some video or audio media--to be able to assign a precise time stamp to a place in a stream of media data. In 1967, the Society of Motion Picture and Television Engineers (SMPTE) introduced a method for doing this, called timecoding. Timecoding is a way of putting time stamps [called timecodes] on recorded media such as film, video, sound, and the like. QuickTime, of course, has its own methods of specifying times within a movie, using time bases, time values, and time Scales. [See Chapter 2, "Control," for a preliminary discussion of these concepts.) But QuickTime also supports storing and displaying SMPTE timecodes. Figure 11.1 shows a frame of a QuickTime movie with a timecode value displayed below the video track. Timecode is displayed using an eight-digit, 24-hour clock that looks like this: hh:mm:ss:ff. The digits represent {from left to right) hours, minutes, seconds, and frames. As you can see, the frame displayed in Figure 11.1 is exactly 14 seconds from the beginning of the movie {assuming that the movie began at timecode 00:00:00:00). The actual timecode values of a specific QuickTime movie can be synthesized by the computer or captured along with the source material. In this chapter, we'll take a look at using timecodes in QuickTime movies. Timecodes are stored in timecode tracks, which are created and managed using the timecode media handler. The timecode media handler is extremely easy to work with; it provides a grand total of 11 functions {of which we'll use only 7 here) and requires us to work with only a handful of data structures. In fact, there is only one mildly difficult concept we'll need to understand: the notion of drop-frame timecode. We'll begin by investigating the standard timecode formats, and then we'll move on to seeing how to create and manage timecode tracks in QuickTime movies.
319
Figure 11.1 A movie frame with timecode displayed.
Figure 11.2 The Test menu of QTTimeCode.
Our sample application for this chapter is called QTTimeCode; its Test menu contains the timecode-specific commands. Figure 11.2 shows the Test menu for movies that do not contain a timecode track. Figure 11.3 shows the Test menu for movies that do contain a timecode track.
320
Chapter 11 Timecode
Figure 11.3 The Test menu of QTFimeCode (second version).
Timecode Standards As we've seen, timecode is expressed using an eight-digit clock, w h e r e the rightmost two digits represent a frame number. There are four s t a n d a r d frame rates used commercially a r o u n d the world, so there are four standard timecode formats: 9 Most film produced in the United States uses a standard of 24 frames per second (fps). 9 Most film produced in Europe and Australia uses a standard of 25 fps, established by the E u r o p e a n Broadcasting U n i o n (EBU); 25 fps is also used for PAL or SECAM video and television. 9 The SMPTE standard for American black-and-white television uses 30 fps. This frame rate is also c o m m o n l y used for audio and CD mastering. 9 American color television and systems based on it {such as NTSC video} use a standard of 29.97 fps. This rate is the result of certain technical decisions made w h e n converting from black-and-white to color television. The oddball here is the SMPTE standard for American color television and NTSC video, which uses a frame rate of 29.97 fps. This is close enough to 30 that people typically consider American color TV to have a frame rate of 30 fps. But 29.97 isn't exactly 30, and the difference can add up. For instance, over a period of one hour, a 30-fps movie will display 108,000 frames, whereas a 29.97-fps movie will display 107,892 frames. This means that, if we use a 30-fps timecode to display the time of a 29.97-fps movie, the movie would be 108 frames (or about 3.6 seconds} longer than a movie that has exactly 30 fps. That is to say, by the time a 29.97-fps movie gets to 108,000 frames, 1 hour and 3.6 seconds has elapsed. For most purposes, an extra 3.6 seconds per hour is pretty insignificant. But on commercial TV, time is money. For example, ABC charged about $2.2 million for a 30-second advertisement during the 2001 Super Bowl. In that
Timecode Standards
321
Figure 11.4 A movie frame with drop-frame timecode.
case, 3.6 seconds is worth about $264,000. So it's sometimes important to get timecode values exactly right. To ensure that 30-fps timecodes displayed by a 29.97-fps movie exactly match the time on a wall clock, SMPTE defined drop-frame tirnecoding, according to which two frame numbers are dropped at the start of every minute, except for every minute that is evenly divisible by 10. (For example, the timecode value 11:31:59:29 is immediately followed by 11:32:00:02.) So, over the course of one hour, 108 frame numbers will be dropped