Prerolling Movies - What, Why, When, and How

Dispatch 13

The synchronized play back of video, sound, and other kinds of media is a difficult task. A simple QuickTime movie consisting of a single video track and a single sound track requires many different software components to play back, including a clock, two media handlers, one or more video decompressors, a sound channel, and two or more data handlers.All of these software components must work together in order to flawlessly play back the media without dropping any frames. In order to insure that the movie will play back as well as possible, it is necessary to preroll the movie before starting it playing. If a movie isn't prerolled before it is played, all the work of preroll must be done while the movie's clock is ticking. This almost guarantees that the movie won't play back as well as possible.

When you preroll a movie, the Movie Toolbox makes sure that all the pieces of software necessary to play back the movie are prepared. This may include loading software components and configuring them with the movie's current settings. It may also require some of the media data to be loaded so that it is immediately available for play back when the movie is started.

QuickTime's standard movie controller takes care of prerolling the movie before it is played, if the movie is played as a result of a user action, such as clicking on the play button. If your application is using the movie controller and wishes to start the movie playing, this can be done using the movie controllers "preroll and play" action. This action takes the desired play back rate as an argument.

MCDoAction(theMovieController, mcActionPrerollAndPlay,
             GetMoviePreferredRate(theMovie));

The movie controller's preroll and play action, as its name implies, first prerolls the movie and then sets it playing at the requested rate.

If your application uses QuickTime's Movie Toolbox to play back movies, there are two choices for how to preroll the movie. Like the movie controller, the Movie Toolbox provides a single function call, StartMovie, which will both preroll the movie and start it playing. Unlike the movie controller, the Movie Toolbox function doesn't allow you to specific the rate to play the movie at, but instead assumes the movie's preferred rate.

StartMovie(theMovie);

StartMovie, just like the movie controller's preroll and play action, first prerolls the movie and then sets it playing. If your application requires more control, the Movie Toolbox provides lower level functions which give you more control.

TimeValue timeNow;
Fixed playRate;
   
timeNow = GetMovieTime(theMovie, nil);
playRate = GetMoviePreferredRate(theMovie);
   
PrerollMovie(theMovie, timeNow, playRate);
SetMovieRate(theMovie, playRate);

If your application needs to start a movie playing as quickly as possible, this solution offers the most control. The application can preroll the movie, and then wait for the appropriate instant to start the movie playing, and then calling SetMovieRate. Some applications mistakenly call both SetMovieRate and StartMovie. This is unnecessary and may in fact cause start up stutters, depending on the order in which the calls are made.

When prerolling a movie, the Movie Toolbox makes use of all the information it has about the movie. This includes its current GWorld, the specificed preroll time and rate, the movie's current dimensions and size, any clipping of the destination (such as an overlapping window), and the destination's video settings (color depth/bit depth) . If any of these are changed after prerolling the movie, all or part of the work performed by the preroll may be invalidated. For example, some applications preroll the movie in a window that is not yet visible. After starting the movie playing, the application makes the window visible. Unfortunately, it is impossible for the Movie Toolbox to determine all the characterisitics of the destination GWorld, such as its color depth or clipping, if it is invisible. This means that the preroll operation may not be able do all the required work, and so the movie will not be able to start playing smoothing. In general, it is best not to make any "Set" calls to a movie, such as SetMovieBox or SetMovieGWorld, after calling PrerollMovie and before calling SetMovieRate. as these could invalidate the work done by PrerollMovie.

One of the reasons that developers preroll the movie with its destination window set to invisible is to avoid having an empty window displayed to the user. Preroll the movie may take some time. This is typically a fraction of a second, but in some cases up to a second or more, depending on the various storage devices and audio and video decoders being used. In order to make sure the user doesn't have to see a blank screen while the movie is prerolled, it is a good idea to display the current frame of the movie while it is prerolled. The best way to do this depends on whether you are using the movie controller or the Movie Toolbox. Of course, in either case, the display of the current frame must be done after the movie's destination window is made visible. If you are using the movie controller, you should call MCIdle.

MCIdle(theMovieController);

If you are using the Movie Toolbox, you should call MoviesTask.

MoviesTask(theMovie, 0);

Another problem that can occur in many applications is that once the window is made visible, the operating system will generate an update event to cause the application to update the window. Unfortunately, this update event will cause QuickTime to have to do extra work. QuickTime has no way of knowing whether the upate event was generated because the window was just made visible or because a portion of the window was uncovered because another window was moved or closed. Therefore, when QuickTime receives an upate event it must completely regenerate the current frame on the screen. Depending on the media types and compression types in the movie, this can result in one or more frames being dropped. Clearly after carefully prerolling the movie, something needs to be done so an unnecessary update event doesn't come along and undo all that work. This problem can be solved by notifying the operating system that the area where the movie is located is not invalid. This must be done after making the window visible. The process of validating the area where the movie is displayed is the same whether you are using the movie controller or the Movie Toolbox.

RgnHandle movieRgn;
   
movieRgn = GetMovieDisplayBoundsRgn(theMovie);
SetPort(theMoviePort);
ValidRgn(movieRgn);
DisposeRgn(movieRgn);

Note that we use the movie's region to perform the validate operation. This is because not all movie's are rectangular in shape, and we only want to validate the pixels which the movie will actually draw to. If your applicaton can be sure that it will only ever work with rectangular movies, for example it is a CD-ROM title that only opens a known set of movies from its CD-ROM, you can simplify the code by only using the movie's bounding box. However, if your application allows the user to open any movie, it is recommended that you use the movie's region rather than its bounding box.

Rect movieBox;
   
GetMovieBox(theMovie, &movieBox);
SetPort(theMoviePort);
ValidRect(&movieBox);

See Also

Inside Macintosh: QuickTime - Movie Toolbox chapter

Inside Macintosh: QuickTime Components - Movie Controller chapter

QuickTime 3 Reference - Movie Toolbox, Movie Controller

Change History

4/26/98 - jph - First published