Nov 99 Getting Started
Volume Number: 15 (1999)
Issue Number: 11
Column Tag: Getting Started
Getting Started with QuickTime
by Dan Parks Sydow
How a program displays a QuickTime movie and movie-controller in a window
For years, QuickTime has been cool. Now, version 4 makes QuickTime amazing. With QuickTime 4 your program's use of movies knows few bounds. As always, your program can open a QuickTime movie in a window that includes aesthetically pleasing, easy to use controls so that the user can play, pause, or step through the movie. But if you're willing to get to know the Movie Toolbox (the movie-related functions that make up this addition to the Macintosh Toolbox), your Mac program can do much more with QuickTime. Streaming movies, special effects (such as transitions, blending, and dimming), video and audio capture, sprites, and much, much more are all available to you, the programmer. Sound exciting? Ready to get going? Not so fast! In this article you won't learn how to implement these programming tricks. Instead, here you'll only learn the basics of QuickTime programming. Getting Started's job isn't to delve deep into the complicated -- it's to introduce and detail the basics of Toolbox technologies so that you'll be ready to move on to those more complicated and really intriguing technologies Apple has developed for Mac programmers. The things your program can accomplish with QuickTime 4 are so interesting and remarkable, a number of articles are necessary in order to convey to you the programming information you need. And that's exactly what MacTech Magazine is doing. In fact, you'll find a QuickTime 4 article in this very issue
After reading this article you'll know how to check the user's machine for the presence of QuickTime, initialize QuickTime, let the user select a movie to play, open a window complete with controllers, and let the user make use of those controls to play (and replay, and step through, and so forth) the displayed movie. Armed with this knowledge, the material in this month's other QuickTime article -- and the material in many subsequent MacTech Magazine QuickTime-related articles -- will certainly be well within your reach.
QuickTime and the Movie Toolbox
On its own, QuickTime doesn't play movies. Instead, QuickTime enables applications that are written with QuickTime in mind to play movies. To give programmers the ability to add movie-playing features to their applications, Apple has added a number of movie-related functions to the system software. Rather than dub this collection a manager, Apple has instead called it another Toolbox -- the Movie Toolbox. Gaining a knowledge of the routines in the Movie Toolbox is key to adding movie-playing capabilities to your programs.
Initializations
Before your program jumps right in using QuickTime, it should verify that the user's machine has the QuickTime extension installed (or that if installed, it isn't disabled) and it should initialize the Movie Toolbox. The first task is accomplished with a call to Gestalt(). Here's the code to use:
OSErr err;
long result;
err = Gestalt( gestaltQuickTime, &result );
if ( err != noErr )
DoError( "\pQuickTime not present" );
Recall from previous articles that when one of the many Apple-defined selector codes is passed as the first parameter, Gestalt() fills in the second parameter with information about the topic of the selector code. In this instance, the selector code is gestaltQuickTime. The returned result will be the version of QuickTime that's on the user's Mac. If your program will be making use of fancy techniques only available in, say, version 4 of QuickTime, then you'll want to examine result to see if it holds a value of 4. If your program isn't doing much more than standard movie playing, you probably won't be interested in which version is present -- just that a version is present. In such a case you can do what I've done in the above snippet -- simply check the value of err. If QuickTime is present, Gestalt() will return a value of noErr. If it isn't present, then err will have some other value.
Once you've established the QuickTime is available, initialize the Movie Toolbox. As the "regular" Toolbox needs initialization (by way of calls to InitGraf(), InitWindows(), and so forth), so too does the Movie Toolbox. A single call to EnterMovies() does the job. If successful (and there's little reason that it won't be successful), EnterMovies() returns a value of noErr:
err = EnterMovies();
if ( err != noErr )
DoError( "\pError initializing the Movie Toolbox" );
Loading a Movie
Before playing a movie, a program needs to open the QuickTime file in which the movie is stored, load the movie data to memory, and then close the file.
In past Getting Started articles we've used a file system specification, or FSSpec, to tell a program where a file is. If we know the name of the file that holds the movie, and if the file is guaranteed to be in the same folder as our application, then the code to accomplish this trick involves one Toolbox call. Assuming the file was named JumpBall, the code would look like this:
OSErr err;
FSSpec movieFileSpec;
err = FSMakeFSSpec( 0, 0, "\pJumpBall", &movieFileSpec );
The file is then opened using a call to the Movie Toolbox function OpenMovieFile(). Pass OpenMovieFile() a pointer to the just-created FSSpec. As the second argument, pass a pointer to a short variable -- this variable will be filled in with a file reference number that can be used in other Movie Toolbox calls later in the program. Finally, pass a permission level at which the file should be opened. The Apple-defined constant fsRdPerm specifies read-only permission, which is adequate for our needs.
short movieRefNum;
err = OpenMovieFile( &movieFileSpec, &movieRefNum, fsRdPerm);
If your program is responsible for deciding which movie to play (perhaps you're writing a game or educational program that displays a particular movie in response to a particular user action), the above technique may be suitable -- your program will know the name of the movie to play, and will know that the movie is present along with the application (assuming you've supplied all the movies with the application). However, many types of programs allow the user to select the movie to play. In this month's example program we do just that -- so you'll want to inspect the included source code to see how to display the standard Open dialog box that lets the user choose the movie to open and play.
With the movie file open, it's time to load to memory the movie data from the file. A call to the Movie Toolbox function NewMovieFromFile() is used here:
Movie theMovie;
OSErr err;
short movieRefNum;
short resID = 0;
Str255 name;
Boolean changed;
err = NewMovieFromFile( &theMovie, movieRefNum, &resID, name,
newMovieActive, &changed );
That's quite a parameter list, so a little explanation is certainly in order. Let's tackle them one at a time:
theMovie A movie exists in the recently opened file -- but the program needs a copy of that movie in memory in order to work with it. NewMovieFromFile() creates that movie in memory. The first argument, theMovie, is of type Movie -- a data type that holds a pointer to a memory block that contains a movie created by the call to NewMovieFromFile().
movieRefNum This is the reference number returned by the recent call to OpenMovieFile().
resID This is the resource ID of the movie's moov resource. If the movie file holds a single movie (typically the case), then a value of 0 can be used to specify that the first (and only) moov resource in the file be used. The moov resource, incidentally, only holds a description of the movie -- the data that is the movie is held in the movie file's data fork.
name This is the name of the movie. To get this name, NewMovieFromFile() looks at the name of the moov resource it's using. If the moov resource hasn't been named (it often isn't), then NewMovieFromFile() assigns name a value of nil.
newMovieActive This fifth parameter is an Apple-defined constant that specifies that the newly created movie be active. A QuickTime movie must be active before it can be played.
changed If for some reason the Movie Toolbox needs to alter any data as it loads movie data to memory (it shouldn't have to), then NewMovieFromFile() will fill this variable with a value of true. More likely, everything will remain as intended, and this variable will end up with a value of false.
With the movie data in memory, your program no longer needs the file that holds the original movie. A call to the Movie Toolbox function CloseMovieFile() closes an open movie file:
CloseMovieFile( movieRefNum );
The only argument to CloseMovieFile() is the movie reference number that was returned by the earlier call to OpenMovieFile().
Displaying a Movie and Movie Controller in a Window
When you look at a QuickTime movie on screen, you see that the movie and a controller reside in a window -- a window, a movie, and a controller can all be associated with one another. With a movie in memory and referenced by a Movie variable, it's time to open a window in which to display the movie. There's nothing much new here -- we're opening a window (a color window by way of GetNewCWindow()) in which to display the movie. The size of the window isn't important -- later on we'll be resizing it to match the size of the movie.
WindowPtr theWindow;
theWindow = GetNewCWindow( kWINDResID, nil, (WindowPtr)-1L );
A movie makes use of a graphics world -- a drawing environment that holds display information for that movie. Before a movie is first played, you'll set the movie's display coordinate system to that of the window in which the movie is to be played. A call to the Movie Toolbox function SetMovieGWorld() sets the display coordinate system of the movie named in the first argument to that of the window named in the second argument. The final argument can be nil (it can be used as a handle to the movie's graphics device structure). Here we assume the movie has already been loaded to memory, as discussed earlier:
SetMovieGWorld( theMovie, (CGrafPtr)theWindow, nil );
The call to SetMovieGWorld() pairs a movie with a window. Before attaching a movie controller to a movie, you'll need to know the width of the movie. A call to the Movie Toolbox function GetMovieBox() gives us that information -- this routine returns a rectangle that holds the dimensions of a movie:
Rect box;
GetMovieBox( theMovie, &box );
Now we have the information necessary to create a movie controller. A call to the Movie Toolbox routine NewMovieController() creates a controller of the appropriate size and attaches it to a movie. The movie to attach to is specified in the first argument. The second argument holds the size of the movie, from which NewMovieController() determines the width of the controller to create. The final argument specifies where within the window the movie should be placed (a movie doesn't have to appear in a window of the same size as the movie -- it could for instance be centered in a window that was larger than the movie). NewMovieController() needs that information so that it can nestle the controller right under the movie. Pass the Apple-defined constant mcTopLeftMovie to specify that the movie will appear snug in the window, with the movie's top left corner in the window's top left corner.
MovieController theController;
theController = NewMovieController( theMovie, &box,
mcTopLeftMovie );
With the movie and controller in place, it's time to resize the already open window. Whether the window was initially opened larger or smaller than the movie isn't of importance -- we'll fine-tune things now. The Movie Toolbox function MCGetControllerBoundsRect() doesn't do anything with a window, but it does return the exact size of a movie and its controller -- information we'll use to resize the window:
Rect rect;
MCGetControllerBoundsRect( theController, &rect );
Recall that NewMovieController() created a controller based on the size of a particular movie. The resulting controller is considered attached to that movie. Given a controller, MCGetControllerBoundsRect() thus knows the overall size of the combination of movie and controller. The function sets the left and top fields of rect to 0 and places the width of the movie in the right field and the height of the movie/controller in the bottom field. Use the right and bottom fields to resize the previously opened window. It's best if the window was created invisible so that all the busy work could be performed before displaying the properly sized window complete with controller and movie:
SizeWindow( theWindow, rect.right, rect.bottom, true );
ShowWindow( theWindow );
Movies and the Event Loop
SetMovieGWorld() paired the movie with the window, and NewMovieController() attached the controller to the movie. The movie/controller/window is perfectly sized, so you'd think that the program is ready to play the movie. Not quite! We need to sneak a few lines of code in the program's main event loop so that the loop can intercept and act upon events that involve a movie controller.
void EventLoop( void )
{
EventRecord event;
ComponentResult movieEvent;
while ( gDone == false )
{
if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) );
{
movieEvent = MCIsPlayerEvent( theController, &event );
if ( movieEvent == 0 )
DoEvent( &event );
}
}
}
This version of EventLoop() should look pretty familiar to you -- with a couple of notable exceptions: the declaration of a ComponentResult variable and a call to a Movie Toolbox function named MCIsPlayerEvent(). After WaitNextEvent() returns an event, we call MCIsPlayerEvent() to examine the event to see if it involved a movie controller. If it did, MCIsPlayerEvent() will handle the event. Yes, this is another one of those powerful, oh-so-handy functions to have at your disposal. It doesn't matter what action the user is performing on the movie controller, MCIsPlayerEvent() takes care of business. If the user clicks the Play button, the movie plays. If the user clicks the Pause button, the moview stopos. And so forth. If the event doesn't involve the movie controller, then we move on to our usual call to DoEvent(). DoEvent() is our own routine that handles events as appropriate for our program.
QTplayer
This month's program is QTplayer. To keep things simple and to the point, QTplayer is a non-menu-driven program. When run, QTplayer displays the standard Open dialog box -- as shown in Figure 1. Use it to locate and open a movie file of your choice. When you do that, the movie appears in its own window, complete with controller. If you have QuickTime 4 on your Mac, you'll see a controller like the one shown on the left of Figure 2. If you have QuickTime 3, you'll instead see a controller like the one on the right side of Figure 2.
Figure 1.Selecting a movie file to open.
Figure 2.Running under QuickTime 4 (left) and QuickTime 3 (right).
Once the movie is displayed, test out the movie controller. Play the movie, pause it, then play it again. Step though the movie, forward and back. When you're convinced that QTplayer works as expected, press any key to quit.
Creating the QTplayer Resources
Start the project by creating a new folder named QTplayer in your CodeWarrior development folder. Launch ResEdit, then create a new resource file named QTplayer.rsrc. Make sure to specify the QTplayer folder as the resource file's destination. The resource file will hold resources of the types shown in Figure 3.
Figure 3.The QTplayer resources.
The one ALRT and one DITL resource are used to define the program's error-handling alert. From previous Getting Started articles you should be quite familiar with that alert. The only other resource needed is a single WIND. This resource defines the window that will hold the QuickTime movie. As mentioned, the size of the window is unimportant -- the program will resize it after the user selects a movie to display. You should mark the window as initially invisible so that it remains hidden while the program resizes it and sets the movie and controller in it.
Creating the QTplayer Project
Start CodeWarrior and choose New Project from the File menu. Use the MacOS:C_C++:MacOS Toolbox:MacOS Toolbox Multi-Target project stationary for the new project. You've already created a project folder, so uncheck the Create Folder check box before clicking the OK button. Name the project QTplayer.mcp, and make sure the project's destination is the QTplayer folder.
Add the QTplayer.rsrc resource file to the new project. Remove the SillyBalls.rsrc file. Go ahead and remove the ANSI Libraries folder from the project window if you want -- the project doesn't use any of these libraries.
Create a new source code window by choosing New from the File menu.. Save the window, giving it the name QTplayer.c. Now choose Add Window from the Project menu to add this empty file to the project. Remove the SillyBalls.c placeholder file from the project window. You're all set to type in the source code.
To save yourself some typing, go to MacTech's ftp site at ftp://ftp.mactech.com/src/mactech/volume15_1999/15.11.sit. There you'll find the QTplayer source code file available for downloading.
Walking Through the Source Code
Because the QTplayer program isn't menu-driven, the listing is shorter than our other example listings. QTplayer.c starts with a couple of constants. The constant kALRTResID defines the ID of the ALRT resource used to define the error-handling alert. Constant kWINDResID defines the ID of the WIND resource used for the window that is to display the QuickTime movie. Constant kSleep is used in the event loop's call to WaitNextEvent().
/********************* constants *********************/
#define kALRTResID 128
#define kWINDResID 128
#define kSleep 7
QTplayer declares a few global variables that are used to keep track of the QuickTime movie. In our discussion of QuickTime code we used local variables to keep tabs on the window, movie, and controller -- the QTplayer code provides an alternate method.
/****************** global variables *****************/
Boolean gDone = false;
WindowPtr gMovieWindow = nil;
MovieController gMovieController = nil;
Movie gMovie = nil;
Next come the program's function prototypes.
/********************* functions *********************/
void ToolBoxInit( void );
void EventLoop( void );
void DoEvent( EventRecord *eventPtr );
void OpenOneMovie( void );
void GetMovieFromFile( void );
void AdjustMovieWindow( void );
void CloseOneMovie( void );
void DoError( Str255 errorString );
The main() function begins with the declaration of a couple of variables. The OSErr and long variables err and result are used in the determination of whether QuickTime is present and in the initialization of the Movie Toolbox -- as discussed in the body of this article. After the Toolbox is initialized, it's time to open a movie, move to the event loop, and finally close the movie when the program ends.
/********************** main *************************/
void main( void )
{
OSErr err;
long result;
ToolBoxInit();
err = Gestalt( gestaltQuickTime, &result );
if ( err != noErr )
DoError( "\pQuickTime not present");
err = EnterMovies();
if ( err != noErr )
DoError( "\pError initializing the Movie Toolbox" );
OpenOneMovie();
EventLoop();
CloseOneMovie();
}
As expected, ToolBoxInit() is identical to previous versions.
/******************** ToolBoxInit ********************/
void ToolBoxInit( void )
{
InitGraf( &qd.thePort );
InitFonts();
InitWindows();
InitMenus();
TEInit();
InitDialogs( nil );
InitCursor();
}
OpenOneMovie() begins with a call to the application-defined function GetMovieFromFile(). That function displays the standard Open file dialog box, opens a movie file, and loads the file's movie to memory. A call to GetNewCWindow() opens the window that is to hold the movie. A call to the application-defined function AdjustMovieWindow() is made to attach a controller to the movie and to resize the window to match the size of the movie. Both GetMovieFromFile() and AdjustMovieWindow() are discussed ahead.
/******************* OpenOneMovie ********************/
void OpenOneMovie( void )
{
GetMovieFromFile();
if ( gMovie == nil )
ExitToShell();
gMovieWindow = GetNewCWindow( kWINDResID, nil,
(WindowPtr)-1L);
AdjustMovieWindow();
}
GetMovieFromFile() begins with a host of local variables:
/***************** GetMovieFromFile ******************/
void GetMovieFromFile( void )
{
OSErr err;
SFTypeList typeList = { MovieFileType, 0, 0, 0 };
StandardFileReply reply;
short movieRefNum;
short resID = 0;
Str255 name;
Boolean changed;
Earlier we discussed how a file can be opened without any user-input. Here we see how easy it is to implement the use of the standard Open dialog box to give the user the power to choose the file to open:
StandardGetFilePreview( nil, 1, typeList, &reply );
The Macintosh Toolbox provides programmers with the StandardGetFile() function. The Movie Toolbox offers an enhanced version of that function -- StandardGetFilePreview(). As shown back in Figure 1, the dialog box displayed by this function offers the user the chance to see a preview image of the file that he or she is considering opening. StandardGetFilePreview() requires four arguments, as described next.
The first argument is a pointer to a filter function -- an application-defined routine that can be implemented to limit the types of files displayed in the list box of the standard Open dialog box. The second argument (discussed next) also is used for this purpose, but a filter function can be used to further define which files should and shouldn't be displayed. Passing a value of nil here means the program doesn't make use of the optional filter function.
The second argument is the number of file types to be displayed in the dialog box list. The standard Open dialog box can easily display four types of files. We're only interested in letting the user see one type of file -- QuickTime movie files.
The third argument defines which type or types of files to display. Each type of file has a four-character file type associated with it. So, if your program can open text files, then you'll want the standard Open dialog box to display files of type 'TEXT'. If your program can also open picture files, then you'd want the standard Open dialog box to display files of type 'TEXT' and files of type 'PICT'. Our QTplayer program can open only movie files, so we want to specify that just files of type 'MooV' be displayed. Apple defines a constant that represents this file type -- MovieFileType. We use this constant in the declaration of a variable of type SFTypeList, setting the other three possible file types to display to 0. Then we pass this list as the third argument to StandardGetFilePreview().
The last argument to StandardGetFilePreview() is a pointer to a variable of type StandardFileReply. After the user dismisses the standard Open dialog box, the Movie Toolbox fills in the fields of this variable. Typically you'll only be interested in two of the many StandardFileReply fields. The sfGood field is a Boolean that will have a value of true if a file was selected and a value of false if the Cancel button was instead clicked. The sfFile field is a file system specification (an FSSpec) for the selected file (if one was indeed selected). Here's how the sfGood and sfFile fields of the reply variable filled in by the call to StandardGetFilePreview() are used:
if ( reply.sfGood == true )
{
err = OpenMovieFile( &reply.sfFile, &movieRefNum,
fsRdPerm );
if ( err == noErr )
{
err = NewMovieFromFile(&gMovie, movieRefNum, &resID,
name, newMovieActive, &changed );
CloseMovieFile( movieRefNum );
}
}
}
If the user selected a file, reply.sfGood will be true, and we'll go on to open the selected file. The Movie Toolbox function OpenMovieFile() does that. Earlier in this article we called OpenMovieFile() like this:
err = OpenMovieFile( &movieFileSpec, &movieRefNum, fsRdPerm);
In that example, movieFileSpec was an FSSpec created and returned by a call to FSMakeFSSpec(). Here in the QTplayer code we'll replace the first argument with the FSSpec returned by the call to StandardGetFilePreview():
err = OpenMovieFile( &reply.sfFile, &movieRefNum, fsRdPerm );
If opening the file is successful, we'll go ahead and call NewMovieFromFile() to load the movie data to memory:
err = NewMovieFromFile( &gMovie, movieRefNum, &resID, name,
newMovieActive, &changed );
This call is the same as the one made in the article's earlier example -- with the exception of the first argument. Here we're using a global variable rather than a local one. NewMovieFromFile() places a pointer to the movie data in gMovie. After that we can close the open file -- it's no longer needed:
CloseMovieFile( movieRefNum );
It was our OpenOneMovie() function that called our GetMovieFromFile() routine. After that, OpenOneMovie() opened a window in which to display the newly loaded movie. Next, OpenOneMovie() called our own AdjustMovieWindow() to associate the movie with the window, create the movie controller and attach it to the movie, and then resize the window to the size of the movie. All of the code in AdjustMovieWindow() has been discussed earlier. The only differences that you'll see are in the scope of the variables: here in QTplayer the window, movie, and controller are all global variables.
/***************** AdjustMovieWindow *****************/
void AdjustMovieWindow( void )
{
Rect box;
Rect rect;
SetMovieGWorld( gMovie, (CGrafPtr)gMovieWindow, nil );
GetMovieBox( gMovie, &box );
gMovieController = NewMovieController( gMovie, &box,
mcTopLeftMovie );
MCGetControllerBoundsRect( gMovieController, &rect );
SizeWindow( gMovieWindow, rect.right, rect.bottom, true );
ShowWindow( gMovieWindow );
}
With a movie open and displayed, it's on to the event loop. The main() function calls EventLoop() to repeatedly check for and respond to events. As described earlier, in this version of EventLoop() we've added a call to MCIsPlayerEvent() to determine if an event is movie controller related. If it is, we can rely on MCIsPlayerEvent() to handle it. If it isn't, then we go ahead and make our usual call to our application-defined function DoEvent() so that our program can process the event.
/********************* EventLoop *********************/
void EventLoop( void )
{
EventRecord event;
ComponentResult movieEvent;
while ( gDone == false )
{
if ( WaitNextEvent( everyEvent, &event, kSleep, nil ) )
{
movieEvent = MCIsPlayerEvent(gMovieController, &event);
if ( movieEvent == 0 )
DoEvent( &event );
}
}
}
Here DoEvent() is a stripped-down version of the function we've seen in previous Getting Started examples. Because the program isn't menu-driven, we're only interested in responding to a press of a key (a mouse-click on the movie controller is caught by MCIsPlayerEvent() back in EventLoop()). If the user presses a key, we quit.
/********************** DoEvent **********************/
void DoEvent( EventRecord *eventPtr )
{
switch ( eventPtr->what )
{
case keyDown:
gDone = true;
break;
}
}
If the user does quit, main() calls the application-defined function CloseOneMovie() to clean up a bit. Here we simply set the global variables to nil to indicate that a movie is no longer open. While this isn't vital in the case of quitting, it does give you an idea of one way to handle the case of the user closing a movie. If your program was to continue executing, it could at any time easily check whether a movie window was currently open by examining the value of gWindow (or gMovieController or gMovie). A value of nil here means no movie window is open, any other value means a movie is in fact open.
void CloseOneMovie( void )
{
gMovieController = nil;
gMovie = nil;
gMovieWindow = nil;
}
DoError() is unchanged from prior versions. A call to this function results in the posting of an alert that holds an error message. After the alert is dismissed the program ends.
/********************** DoError **********************/
void DoError( Str255 errorString )
{
ParamText( errorString, "\p", "\p", "\p" );
StopAlert( kALRTResID, nil );
ExitToShell();
}
Running QTplayer
Run QTplayer by selecting Run from CodeWarrior's Project menu. After compiling the code and building a program, CodeWarrior runs the program. The standard Open dialog box appears. Find a QuickTime movie (any movie) on your local disk and select it. Doing that opens the movie and displays it in a window. After playing the movie and testing the controller, press any key to quit the program.
Till Next Month..
In this article we opened a movie and placed the movie and a movie controller in a window. Be aware that your program can forego the movie controller. While it's very user empowering, your program might have need to simply open a movie and play that movie on its own -- without intervention from the user. To do that you'd begin by having the program -- rather than the userchoose a movie to play (look back at the FSSpec information before the source code walkthough). That's a part of the task. Now look over the QuickTime edition of Inside Macintosh if you need a few tips on how to implement the rest of this technique.
We didn't elaborate on how a program plays a movie on its own because we wanted to jump into the fun, fancy stuff -- like the movie controller. And we wanted to ready you for the much more interesting stuff to come -- the more advanced movie manipulating, editing, and playing features that QuickTime 4 is capable of. If you're interested in more QuickTime examples, let me know by e-mailing me at dan@sydow.com. Then in next month's article we can touch on some more QuickTime features. Keep in mind, though, that we're here not to teach you everything there is to know about QuickTime, but rather to prep you for all the interesting QuickTime-related articles to be found elsewhere in MacTech in this month's issue, as well as upcoming issues...