To inaugurate this new column on QuickTime, we'll take a look at ten useful tips for
QuickTime application developers. This is certainly not an exhaustive list, but itis an
important one.
Some of the tips describe pitfalls that need to be avoided, while others are simply
clarifications. Let's take a closer look at each one.
10. Working around data reference limitations.
A current limitation of QuickTime is that each media can have only one data reference
to a media data file. This isn't a problem except when you start cutting and pasting
between tracks that refer to different media. You'll then be required to copy the media
data from one media data file to another. For example, InsertTrackSegment will copy
media data between media if the tracks refer to different media.
Calls like GetMediaDataRefCount, AddMediaDataRef, and GetMediaDataRef will reflect
the "one data reference" limitation by only accepting index values of 1. You can't
replace an existing media data reference in QuickTime 1.0, but you can in QuickTime
1.5, with a new call, SetMediaDataRef. Using this routine is a common way of
manuallyresolving media data references that may have been moved by an application.
For example, if you move a movie data file onto a different volume, you can update the
alias using the Alias Manager and update the data reference for the movie with
SetMediaDataRef.
9. Using GetMovieNextInterestingTime.
Since QuickTime is time based rather than frame-number based in the way it deals
with temporal video data, a common question is how to get information about movie
frames, such as frame rate. The answer is to use GetMovieNextInterestingTime.
This function allows you to step quickly and easily through interesting times in a
movie. For example, for an estimate of the frame rate of a movie, you could use
GetMovieNextInterestingTime to count the total number of frames in the movie and
divide it by the total duration of the movie. Likewise, you could use
GetMovieNextInterestingTime to identify the 600th frame in a movie. Since the
internal data structure of QuickTime movies is optimized for accessing this type of
information, GetMovieNextInterestingTime and the other GetNextInterestingTime
calls are very efficient.
8. Not calling ExitMovies.
One recommendation that contradicts QuickTime 1.0 documentation is that applications
should not call ExitMovies before quitting. QuickTime calls this function at
ExitToShell time, and it's safer to allow QuickTime to release private storage and
component connections at that time. This prevents problems such as closing
components in the wrong order. For example, the proper way to clean up after a
movie that uses a standard movie controller is to dispose of the movie controller first,
and then dispose of the movie. If done in the reverse order, there may be adverse
consequences.
7. Getting a movie's unscaled size.
An application should save the movie box obtained with GetMovieBox when a movie is
loaded so that it can retrieve the intended offset and scaling of the movie for
playback. However, some applications may also want to get the unscaled size, and
there isn't an intuitive way to get it. Since the programmatical effect of calling
SetMovieBox is that the movie matrix is changed to reflect the new offset and
scaling, you can easily get the movie box for an unscaled movie by setting the movie
matrix to the identity matrix; using the utility routine SetIdentityMatrix along with
SetMovieMatrix accomplishes this. Then GetMovieBox will return the unscaled size
and offsets.
However, there's a loophole. If a track inside the movie is scaled, there may still be
scaling in playback since QuickTime supports transformation matrices for movies and
for tracks within a movie. Therefore, when working with scaling, applications need to
pay attention not only to the movie's scaling but to the tracks' scaling as well.
6. Avoiding the Movie Toolbox when using the standard movie controller.
When using the standard movie controller, you should almost never use any Movie
Toolbox routines that control movie playback or change movie characteristics. For
example, it would be a mistake to call StartMovie to start playing a movie. Instead,
use the movie controller equivalent, MCDoAction with mcActionPlay. Calling
StartMovie directly causes the movie to play but with the controller's button in the
pause state, not reflecting that the movie is playing back. Similarly, to set looping,
you would use MCDoAction with mcActionSetLooping. Bypassing the movie controller
by using the Movie Toolbox routines directly on a movie controlled with a movie
controller can have dire consequences. As an example, if you set looping for a movie
before creating a controller with NewMovieController, you'll cause the Macintosh to
crash. Don't let it happen to you!
5. Prerolling a movie for improved playback.
Prerolling can improve playback performance by allowing QuickTime to do
preliminary initialization. Since PrerollMovie is passed the movie time and rate, it
can fill buffers and caches optimally to prevent initial stuttering. Normally,
QuickTime automatically prerolls the movie for you. For example, if you call
StartMovie, you don't need to also call PrerollMovie, since StartMovie prerolls the
movie for you. The QuickTime 1.5 documentation describing the StartMovie call states
this clearly. Likewise, the standard movie controller is optimized to preroll whenever
the user starts a movie with the keyboard or mouse. If you call PrerollMovie in
these situations, the second PrerollMovie is redundant and will simply waste time.
In all other cases, prerolling by calling PrerollMovie is recommended before
initiating playback. For example, you should call PrerollMovie before
SetMovieRate.
4. Using CustomGetFilePreview with custom dialogs.
If you use CustomGetFilePreview with custom DLOG and DITL resources, you should be
aware of a bug with the System 7 pop-up menu CDEF: pop-up menus used in
conjunction with black-and- white grafPorts are shifted to the wrong location
within the dialog box. The simple workaround is to force the dialog to be a cGrafPort
by adding a 'dctb' resource with the same ID as the DLOG and DITL resources. You can
easily create a 'dctb' resource with ResEdit by selecting the Custom color button in
the DLOG resource template window. For more information on the 'dctb' resource, see
the Dialog Manager chapter inInside Macintosh: Macintosh Toolbox Essentials (or in
Inside Macintosh Volume V).
3. Conditionally registering a component that requires a hardware
device.
If you write a component that requires a hardware device, you should set the
wantsRegisterMessage flag to give your component an opportunity to verify that the
specific hardware is properly installed. If the hardware isn't available, you can
then indicate to the Component Manager that you don't want the component
registered. The register routine, called with selector kComponentRegister, should
return FALSE if it does want to be registered and TRUE if it doesn't.
One thing to be aware of is that even during registration, the component will be opened
with OpenComponent and closed with CloseComponent. Therefore, you can expect
OpenComponent before the ComponentRegister routine is called, and CloseComponent
after ComponentRegister is called.
For example, if you have a 'vdig' that works with a NuBus video digitizer card, each
time that OpenComponent is called you can check whether the hardware is correctly
installed, and then return that status when ComponentRegister is called by the
Component Manager.
2. Detaching a movie controller properly.
If you want to place the standard movie controller in a different window or location
from its usual placement directly below the movie, you must detach the movie
controller. Follow these steps:
The movie will remain in whatever port it was assigned to using SetMovieGWorld. If
MCSetControllerPort isn't called (step 3), the controller will remain assigned to the
movie's port when NewMovieController is called.
For example:
SetMovieGWorld(myMovie, (CGrafPtr) myWindow, 0);
mcMC = NewMovieController(myMovie, &movieBounds,
mcTopLeftMovie + mcNotVisible);
MCSetControllerAttached(mcMC, FALSE);
MCSetControllerPort(mcMC, myOtherWindow);
MCPositionController(myMC, &movieBounds,
&newControllerRect, mcTopLeftMovie);
MCSetVisible(myMC, TRUE);
1. Calling MaxApplZone from every application.
Not calling MaxApplZone in an application is the reason why many simple QuickTime
playback applications play back movies poorly. Because the Memory Manager grows
the heap only if there isn't any purgeable or free space left, QuickTime doesn't
have the space it needs to play back a movie optimally. Since there's no penalty or
drawback for calling MaxApplZone, all applications should call the routine during
initialization. In fact, MaxApplZone should be your first Macintosh Toolbox call,
because initializing QuickDraw and other managers could allocate memory.
We hope these tips will help you avoid some of the most common pitfalls of QuickTime
development. With so many developers writing QuickTime applications and adding
QuickTime support into existing applications, we want the journey to be as smooth as
possible. We'll keep you updated and informed by continuing to bring you insightful
tips and details about QuickTime in this column. Watch for it!
JOHN WANG (AppleLink WANG.JY) is enjoying his youth in the playpen of the
Printing, Imaging, and Graphics (PIGs) group in Developer Technical Support at
Apple. When he's not engaged in piglet activities, he can be found on a golf course or
hogging the road with his Mazda Miata. No one has trouble identifying John's car, since
he often cruises the California highways with his dog, Skate. In return, Skate promises
to drive safely. *
For more information on the Component Manager, see the QuickTime or
System 7.1 documentation on this subject, and see Gary Woodcock and Casey King's
article, "Techniques for Writing and Debugging Components," in develop Issue 12. *
Thanks to the developers who have made this list possible and to Bill Guschwan, Peter
Hoddie, and Guillermo Ortiz for reviewing this column. *