Programming With QuickTimeVR
Volume Number: 13
Issue Number: 7
Column Tag: Multimedia
Programming With QuickTime VR
by Tim Monroe and Bryce Wolfson, Apple Computer, Inc.
A look at the new API for managing QuickTime VR movies
QuickTime VR is the part of the QuickTime Media Layer that allows users to
interactively explore and examine photorealistic, three-dimensional virtual worlds
and objects. For several years, MacOS and Windows users have been able to play back
QuickTime VR content using standard navigation controls. With version 2.0, QuickTime
VR now supports a C API that allows developers to customize and extend the user's
virtual experience. Here you'll find everything you need to know to get started
supporting QuickTime VR in your application.
QuickTime VR is certainly one of the hottest Apple technologies today. Dozens and
dozens of CD titles have appeared in the past months that depend on QuickTime VR.
More significantly, the World Wide Web now serves up literally thousands of
QuickTime VR movies. A large part of this popularity stems from the fact that the
amount of data required to display a complex, photorealistic panorama using
QuickTime VR is much smaller than would be required to model that panorama in detail
using a standard 3D graphics application. This, together with the fact that no run-time
rendering is occurring, drastically reduces the amount of CPU horsepower and RAM
required to immerse the user in a realistic 3D environment. QuickTime VR can
transport the user from the tightest passageway deep inside the pyramids to the
wide-open expanse of the space shuttle payload bay.
But, to paraphrase Al Jolson, you ain't seen nothin' yet, folks. Apple has recently
introduced a C language programming interface to QuickTime VR -- called the
QuickTime VR Manager -- that provides a large set of tools for extending and
customizing the user's virtual experience. The QuickTime VR Manager provides the
necessary hooks for you to add your own custom processing to VR movie playback and
to integrate QuickTime VR content playback with other technologies, particularly with
other multimedia technologies. For instance, you can very easily integrate Apple's
SoundSprocket with QuickTime VR to attach sounds to specific locations in a panorama.
Or, you can play QuickTime movies on the screen of a television in a panorama. Or, you
can embed QuickDraw 3D objects (even moving objects!) in a panorama or object node.
Take your favorite technology and, chances are, there's a cool way to integrate it with a
VR panorama or object.
In this article, we'll explain some basic ways of using the QuickTime VR Manager in
your application. We start by reviewing some simple but important aspects of
QuickTime movie support. Then we move into programmatic control of QuickTime VR
movies by showing how to use standard Movie Toolbox and movie controller functions
to operate on QuickTime VR movies. Finally, we'll describe the QuickTime VR Manager
itself and present some code that demonstrates a few of its capabilities.
Before reading this article, you should be familiar with the basic capabilities and
operations of QuickTime VR. At the very least, you should have opened some panoramas
or object movies using a QuickTime player (for instance, MoviePlayer or
QTVRPlayer) and have a good understanding of the VR user interface (panning and
tilting, zooming in and out, triggering hot spots, and so forth). You can also get the
necessary background information by looking at the first dozen pages of the book
Virtual Reality Programming With QuickTime VR 2.0, the developer documentation for
the QuickTime VR Manager.
Back To Basics
The first thing to keep in mind is that QuickTime VR movies are just QuickTime
movies, at least in the way the movie data is stored in files. The image data for
panoramas and objects is stored in standard QuickTime video tracks in movie files.
Other data (such as names of the nodes in a scene) is stored in data atoms in the movie
resources. What's different about QuickTime VR is the way in which the image data is
handled. In a QuickTime movie, frames of a movie are read from a video track and
displayed in sequence to the user. In a QuickTime VR movie, the image handling is more
complicated, because the image to be displayed depends more heavily on user
interaction. In an object movie, for instance, the user can pan left or right, tilt up or
down, or zoom in and out (among other things). These actions typically require a new
frame from the movie's video track to be displayed. The new frame, however, may or
may not follow the current frame in the movie's video track.
Displaying the appropriate panorama or object images in response to user actions is
the responsibility of the QuickTime VR movie controller, which is a standard
QuickTime movie controller. Every QuickTime VR movie contains a special piece of
user data that identifies the movie controller for the movie. This user data is examined
by the Movie Toolbox when an application calls the NewMovieController function to
create a movie controller for the movie. If the QuickTime VR extension is installed and
the QuickTime VR movie controller component is therefore available, the Movie
Toolbox locates that controller and assigns it to that movie.
Now here's the payoff: if you've done things right, your QuickTime application already
supports QuickTime VR! Go ahead and try it: launch your QuickTime-savvy
application, select Open from the File menu, and then choose a QuickTime VR movie.
(Easier still, just drag the VR movie icon onto your application's icon.) If everything
goes according to plan, the VR movie will open correctly and you'll be able to navigate
within the panorama or manipulate the object in all the right ways. This is because, as
we've just said, the QuickTime VR file contains information that specifies the
QuickTime VR movie controller instead of a QuickTime movie controller. It couldn't be
any easier.
This payoff, however, has a catch: to get VR movie playback, you have to support
QuickTime in the right way. Part of what that means is that you have to call
NewMovieController to associate a movie controller with a movie. Years ago, Peter
Hoddie voiced this warning in a develop column: "When you need a user interface for
playing a movie, you should use NewMovieController to create a movie controller
appropriate for use with that movie. A common mistake is to instead use the Component
Manager routine FindNextComponent or OpenDefaultComponent to locate a movie
controller. This finds the first movie controller in the system's list of registered
components. QuickTime has always contained only one movie controller, so this worked
fine. However, future versions of QuickTime will almost certainly include other movie
controllers, so the first one isn't necessarily the most appropriate one." (Hoddie, p.
22)
These "future versions" of QuickTime are here now, and one of them is QuickTime VR.
So, to support VR movies, you must call NewMovieController instead of the Component
Manager. More generally, you should make sure that you've followed all the advice in
Hoddie's important article. It won't take you long to do so, and it will make it easier to
support QuickTime in all its manifestations.
Beyond the Basics
Once you've implemented basic -- and correct -- QuickTime movie playback support
in your application, there are still a few other things you should do to handle
QuickTime VR movies. In particular, you'll want to enable and disable menu items
correctly and to display the correct cursor when it's outside the movie window.
Happily, you can do each of these things with just a few lines of code. We're supposing