December 92 - TIME BASES: THE HEARTBEAT OF QUICKTIME
TIME BASES: THE HEARTBEAT OF QUICKTIME
GUILLERMO A. ORTIZ
A time base is the heartbeat of a QuickTime movie. It keeps the movie going and tells
the Movie Toolbox when to stop and when to display the next frame. This article
explores the concept of time bases and shows how you can use time bases to affect the
behavior of movies as well as how to use time base callback procedures for timing
purposes.
In a basic sense, a time base can be viewed as the black box that maintains the
temporal characteristics of a QuickTime movie. When a movie is playing, some of its
temporal characteristics are obvious: it has a duration, it's "moving" or not, and so on.
Some of the not-so-obvious characteristics that a time base keeps track of are also
important, such as the clock that governs the passing of time as far as the movie is
concerned and whether the movie is looping.
Time bases are created dynamically by the Movie Toolbox each time a movie is opened,
rather than being stored with a movie. Time bases can also exist by themselves, with
no movie attached, and can therefore be used to time other dynamic events, much as
you would use a Time Manager task.
The QuickTime Movie Toolbox provides a high-level interface that lets you modify all
the parameters of a movie, some of which implicitly change its associated time base.
Most applications therefore will never need to manipulate time bases directly.
Nevertheless, there are situations in which it's necessary to access time bases more
directly, such as the following:
• when a document presents multiple views of a movie and all views need to
be kept in sync
• when you need to take advantage of the callback functions of a time base
• when you're writing a custom movie controller
This article addresses these situations.
THE ARROW OF TIME
First let's define some of the terms related to the way QuickTime treats time:
• Time scale: the number of units into which a second is subdivided. For
most QuickTime movies, the time scale is set to 600, meaning that the
smallest fraction of time measurement for the movie is 1/600th of a second.
• Rate: the multiplier for the time scale. The rate controls how fast the
movie plays. When the rate is 1.0, the movie plays at its normal speed,
meaning that for each second of play the movie's time advances a number of
units equal to the time scale. If the rate is between 0.0 and 1.0, the movie
plays in slow motion, and fewer units are counted off per second of play. A
negative rate implies that the movie is playing backward. A rate of 0 means
that the movie is stopped.
• Time value: indicates where we are in the movie being played back. The
time value is given as a number of time scale units. When a movie is playing
forward from its start, the current time value can be calculated as time
elapsed (in seconds)* time scale* rate
You can think of a time base as a dynamic container that holds the following
information about a process, normally a movie: the time source (either the clock being
used as the master clock or the master time base); the time bounds (the start and stop
time values) and the current time value; the rate; the time base flags, indicating
different conditions for the time base; and a list of callback routines.
Figure 1 illustrates these concepts and shows how they interact. The figure assumes
that the clock or time source ticks at a constant speed; however, you could conceivably
use a clock that runs at a varied speed, which would make the movie go faster and
slower in sync with the clock.
Figure 1 doesn't show the effect of the time base flags. In QuickTime versions 1.0 and
1.5, two mutually exclusive flags are defined -- loopTimeBase and
palindromeLoopTimeBase. The loopTimeBase flag causes the time base to go back to the
start time value when it reaches the stop time value (or vice versa if the movie is
playing in reverse); palindromeLoopTimeBase reverses the direction of play when it
gets to the start or stop value of the time base.
Figure 1 Time Concepts in a QuickTime Movie
THE BASIC STUFF
The QuickTime Movie Toolbox is the best mechanism for manipulating movies and their
parameters. The high-level calls provided by the Toolbox are all that most
applications will ever need. Using graphics as an analogy, suppose that you wanted to
draw a complicated image. The easiest way to do this would be with QuickDraw, by
calling DrawPicture, but you could also interpret the picture by hand and execute its
opcodes individually or even set the video RAM pixels directly! Similarly, when
working with a movie, you can work directly with its time base, but it's best to let the
Movie Toolbox do as much as possible -- not because it's the only way, but because it's
safer, it lessens the chances for compatibility problems, and it's simpler. Thus, for
time bases associated with movies, it's best to call SetMovieTime rather than
SetTimeBaseTime and to call SetMovieMasterClock rather than
SetTimeBaseMasterClock.
For those cases in which it makes sense to access and modify time bases directly (as in
the scenarios mentioned earlier), the Movie Toolbox provides procedural interfaces
that allow you to do so. The sample program TimeBaseSimple provided on theDeveloper
CD Series disc shows how to get a time base from a movie, how to interrogate the time
base, and how to change some of its parameters.
Figure 2 shows the window displayed by TimeBaseSimple. This window displays the
duration of the time base (in most cases the same as the duration of the movie), a
number obtained by subtracting the start time value from the stop time value. It also
shows the rate at which the movie is playing, the preferred rate (a value normally set
when the movie is created; it will differ from the rate if the movie is stopped or is
playing in reverse due to palindrome looping), the name of the clock being used, and
the type of looping in effect.
Figure 2 TimeBaseSimple Window
Through this window, the user can set the preferred rate, which is the rate the Movie
Toolbox and the standard movie controller use to set the movie in motion. Radio buttons
allow the user to specify the type of looping via the time base flags. The user can also
scan the movie backward and forward by clicking the shuttle control in the top left of
the window. This control is included in the sample to show how to go forward or
backward in the movie by changing the current time value in the movie's time base.
GETTING AND CHANGING A TIME BASE
Before you can begin working with a time base, you have to get it. TimeBaseSimple
does this with the following line:
tb := GetMovieTimeBase(gMoov); (* get movie's time base *)
GetMovieTimeBase returns the time base associated with the movie gMoov. The
variable tb receives this value.
Getting the clock information. Once you've retrieved the time base, you can get
the information about it. TimeBaseSimple acquires the information regarding the
master clock in order to display its name in the window. The clock information is
obtained via the Component Manager. First we obtain the clock component being used
by the time base; then we use it to get the information from the Component Manager.
clock := GetTimeBaseMasterClock(tb);
(* instance of clock being used *)
err := GetComponentInfo(Component(clock), cd, Handle(clockN),
NIL, NIL);
In the variable cd, a ComponentDescription record, GetComponentInfo returns the type
of component, the subtype, the manufacturer, and the component flags. Note that the
program could be written to pass NIL instead, because the information received is not
used. clockN is a handle in which GetComponentInfo returns the name of the component,
which is what we're really looking for.
Note also that when a time base has been enslaved to another (as discussed later),
GetTimeBaseMasterClock returns NIL. To ensure there's a master clock associated with
a time base,the application should first call GetTimeBaseMasterTimeBase; a NIL result
indicates that the time base has a master clock, whereas a nonzero result indicates that
a master time base exists that contains the master clock.
Getting and changing the time values. You can get the start and stop time values
for a time base as follows:
scale := GetMovieTimeScale(gMoov); (* first get the time scale *)
startTimeValue :=
GetTimeBaseStartTime(tb, scale, startTime);(* get start time *)
stopTimeValue :=
GetTimeBaseStopTime(tb, scale, stopTime); (* get stop time *)
Note that the start and stop times returned are given in terms of the time scale being
passed; this means that we can get different values for the same time point, depending
on the granularity we require. As a matter of fact, in TimeBaseSimple, when we're
preparing the shuttle control, we get the same values but with a different scale:
shuttleScale := moovScale DIV 10;
localDuration := GetTimeBaseStopTime(tBase, shuttleScale, tr);
localDuration :=
localDuration - GetTimeBaseStartTime(tBase, shuttleScale, tr);
The shuttle control in TimeBaseSimple lets you scan the movie backward and forward.
This is implemented by changing the current time value for the time base, which looks
something like this:
SetTimeBaseValue(gTBState.tBase, value*10, gTBState.moovScale);