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);
(* 'movie scale/10' tick *)
Setting the rate. Although you can obtain the current rate for a time base and set the rate directly, for
a time base associated with a movie a better approach is to make Movie Toolbox calls such as
StartMovie or SetMovieRate. The Movie Toolbox executes these calls by changing the time base
associated with the movie. For example, StartMovie gets the preferred rate and sets the time base rate
to it, setting the movie's time base in motion.
When the movie is being controlled by the standard movie controller, it's
important to call MCMovieChanged if you change any movie characteristic, such as the rate or the
current time value, to keep the controller in sync with the new settings. As mentioned earlier, it's
better to use high-level interfaces to enact these changes; for example, to change the rate via the
movie controller, you can call MCDoAction(mc, mcActionPlay, newRate).
Using the time base flags. When you access a time base directly, you can set its movie to loop, either
normally or backward and forward, by setting the time base flags. GetTimeBaseFlags retrieves the
flags for inspection, and SetTimeBaseFlags modifies the flags. In TimeBaseSimple, the SetTBLoop
routine sets the looping flags:
(* Changes the state of looping in the movie if needed. *)
PROCEDURE SetTBLoop(newFlags: LONGINT);
VAR targetTB: TimeBase;
BEGIN
targetTB := gTBState.tBase; (* the movie's time base *)
SetTimeBaseFlags(targetTB, newFlags); (* change it *)
gTBState.flags := newFlags; (* remember new state *)
END;
Now that you've seen how you can access the state information of a time base, let's look at some of
the possible uses of time bases.
TIME SLAVES
One interesting situation arises when you need to play back two or more instances of a movie
simultaneously. In such situations you can synchronize the movies by enslaving all the instances to
one time base. The central idea behind this is to have control of the movie's time flow pass through a
single point instead of having a number of individual time bases running at the same time. The
sample program TimeBaseSlave on the
Developer CD Series disc shows how to do this.
TimeBaseSlave splits the window in which the selected movie is to play into four parts, with the
quarters rotating while the movie is playing back. Figure 3 shows the TimeBaseSlave window at its
four stages of playback.
Figure 3 TimeBaseSlave Window at Its Four Stages of Playback
The basic programming strategy is as follows:
- Get the time base associated with one of the instances of the movie.
- Force the time base from step 1 to be used for the other instances.
- Start playing the first instance of the movie, controlling it in any way you like.
(TimeBaseSlave starts the movie and sets it back to the beginning when it reaches
the end.)
- The other instances of the movie will follow blindly.
The EnslaveMovies routine in TimeBaseSlave takes care of all this:
FUNCTION EnslaveMovies: OSErr;
VAR err: OSErr;
masterTimeBase: TimeBase;
slaveZero: TimeRecord;
slaveZeroTV: TimeValue;
masterScale: TimeScale;
count: INTEGER;
BEGIN
err := noErr;
masterTimeBase := GetMovieTimeBase(gMoov[1]);
{* time base of first movie instance *}
masterScale := GetMovieTimeScale(gMoov[1]);
{* needed for SetMovieMasterTimeBase *}
slaveZeroTV :=
GetTimeBaseStartTime(masterTimeBase, masterScale, slaveZero);
{* ditto *}
FOR count := 2 TO 4 DO (* slave all movies to first time base *)
BEGIN
SetMovieMasterTimeBase(gMoov[count], masterTimeBase,
slaveZero); {* now we do it *}
(* real programmers do check for errors *)
err := GetMoviesError;
IF err <> noErr THEN
BEGIN
ErrorControl('SetMovieMasterTimeBase failed');
LEAVE;
END;
END;
EnslaveMovies := err;
END;
Once the slave instances of the movie have been set to obey the first time base, their behavior will
mimic the first movie's actions. In the TimeBaseSlave code, it appears that only the first instance is
started and that only it is rewound when the end is reached. These actions are accomplished in
TimeBaseSlave by calls to StartMovie and GoToBeginningOfMovie, respectively, with the first
movie passed as a
parameter.
You could use this technique to play different movies but have all of them under a single control. It
might also be useful when no movies are involved at all but time bases are being used for timing
purposes.
TIMELY TASKS
TimeBaseSlave also shows how to take advantage of the callback capabilities of time bases. Callbacks
are useful when an application needs to execute given tasks when the time base passes through certain
states. You can program time base callbacks to be triggered under the following conditions:
- when a certain time value is encountered (callBackAtTime)
- when a rate change occurs (callBackAtRate)
- when there's a jump in time (callBackAtTimeJump)
- when the start or stop time is reached (callBackAtExtremes)
Passing callBackAtTime to NewCallBack shows the use of callbacks that are executed at a specified
time value. TimeBaseSlave uses the callback service to rotate the movie pieces at regular intervals; we
ask to be called every three seconds in movie time.
Note that the time value triggering the callback depends on the rate of the time base. In other words,
the time value specified will never be reached if the movie isn't playing (if the rate is 0). If the rate is
something other than 1.0 (if the movie is accelerated or is moving in slow motion or in reverse), the
specified break will come every three seconds in movie time, not clock time.
CREATING A CALLBACK
First TimeBaseSlave has to create a callback. This could be accomplished as follows:
cb := NewCallBack(tb, callBackAtTime);
Since we want to be called at interrupt time, however, the line looks like this:
cb := NewCallBack(tb, callBackAtTime + callBackAtInterrupt);
The variable cb receives a callback, which depends on the time base tb. The callback will be executed
at specific times and can be scheduled to fire at interrupt time.
NewCallBack moves memory, which means that you can't create a callback while in an interrupt
handler. Electing to be called at interrupt time has an advantage over normal interrupt-driven tasks,
however, as I'll explain later.
PRIMING THE CALLBACK
Once we're satisfied that the callback was created (cb <> NIL), we proceed to prime the callback. At
this point we have only the hook into the time base; priming the callback schedules it to call us. This
is accomplished by CallMeWhen, as follows:
err := CallMeWhen(cb, @FlipPieces, callWhen, triggerTimeFwd,
callWhen, scale);
FlipPieces is the routine that we want to have called when the specified time value arrives. The
callWhen variable is passed both as a refCon (the third parameter) and as the time to trigger the
callback (the fifth parameter), the idea being that FlipPieces will need to know the current time. Of
course, the refCon parameter can also be used for any other purpose you may see fit.
The time at which the callback is triggered is given a frame of reference by the scale parameter.
Remember that a time value without a time scale has no meaning at all. Finally, triggerTimeFwd
means that our routine will be called only when the movie is moving forward. This is reasonable
since TimeBaseSlave plays back the selected movie in forward motion only.
THE FLIPPIECES ROUTINE
The routine responsible for servicing the callback follows a simple interface and is defined in
TimeBaseSlave as follows:
(* CallBackProc *)
PROCEDURE FlipPieces(cb: QTCallBack; refCon: LONGINT);
(* The refCon parameter contains the time that triggers the
callback; this is the value passed to the CallMeWhen routine. *)
VAR j: INTEGER;
callWhen: LONGINT;
scale: TimeScale;
stop: LONGINT;
tr: TimeRecord;
tb: TimeBase;
err: OSErr;
BEGIN
stage := (stage + 1) MOD 4;
FOR j := 1 TO MoviePieces DO
ShiftMoviePieces(j); (* turn the movie pieces around *)
scale := 100; (* 100 units in this scale means 1 second *)
callWhen := refCon + 3*scale; (* call me in 3 seconds *)
tb := GetCallBackTimeBase(cb); (* needed for next line *)
stop := GetTimeBaseStopTime(tb, scale, tr);
IF callWhen > stop THEN (* wrap around the three seconds *)
callWhen :=
GetTimeBaseStartTime(tb, scale, tr) + callWhen - stop;
(* now to really reprime the callback *)
err := CallMeWhen(cb, @FlipPieces, callWhen,
triggerTimeFwd + callBackAtInterrupt, callWhen, scale);
END;
TimeBaseSlave does the actual splitting of the movie into different views by creating four instances of
the same movie and setting the movie clipping region for each one to be the rectangle in which eachis expected to display. When it's time to move the pieces, the movie box of each instance is offset to
cover the next spot. Take a look at SplitMovie and ShiftMoviePieces to see the code.
A FEW CONSIDERATIONS
Inquisitive readers will have noted that when calling CallMeWhen, TimeBaseSlave uses both
noninterrupt and interrupt-time invocations. This was done to illustrate one of the advantages of
using Movie Toolbox callbacks: the Toolbox takes care of setting up the A5 world when your service
routine is called. Having the A5 world set up properly is useful when your program needs to access
global variables; other interrupt handlers can't count on A5 being right when they're invoked.
Using time base interrupt callback routines does not, however, liberate the application from the
normal limitations of interrupt-servicing routines; for example, you can't move memory.
As mentioned earlier, although time bases are created automatically when a movie is opened or
created, they can also exist on their own. If an application requires services that allow control over
the passing of time, it can create a time base and use callbacks to trigger the service routines required.
Keep in mind that even when a time base has no movie, the application must still call MoviesTask to
guarantee that callback routines will get time to run.
OTHER TYPES OF CALLBACKS
Time base callbacks can also be triggered by a change in the rate or by a jump in the time value. A
change in the rate occurs when the movie is stopped while it's playing, when a movie is set in motion,
or when the playback speed is somehow changed. A jump in time occurs when the current time value
in the time base is set to a value outside the normal flow -- for example, when a movie that's playing
is set back to the beginning. In addition, QuickTime 1.5 introduces callbacks "at extremes" that can
be triggered when the time base time reaches the start or stop time.
These three means of triggering a callback are of interest only if the code is tracking the behavior of
the movie, as a movie controller or a media handler would need to do; the constants used for calling
NewCallBack in these cases are callBackAtRate, callBackAtTimeJump, and callBackAtExtremes.
FINALLY
If you'd like to play with the sample programs, you may want to try some variations. For instance, it's
very easy to modify TimeBaseSlave to have all the movies play at their own beat, with separate time
bases, and compare the performance with the original TimeBaseSlave. You could also modify
TimeBaseSimple to see the time values obtained with different time scales.
Time bases are an important part of the QuickTime Movie Toolbox. Understanding their role in the
way movies play back can be extremely important for developers trying to push the envelope in
writing new and innovative QuickTime applications. This article has opened the door; now it's up to
you to decide whether this route will prove beneficial to your efforts.
HIGHLIGHTS OF QUICKTIME 1.5 NEW FEATURES
Listed below are some of the more significant features of QuickTime 1.5.
- Photo CD: Using QuickTime 1.5 and the Photo CD Access extension, you can work with Kodak Photo
CDs on your Macintosh. Photos on the CD appear as standard PICT files and can be opened in any
application that opens pictures.
- Compact video compressor: A new compressor has been added that provides high-quailty, low data rate
playback.
- Movie import: Any application that opens movies using QuickTime's Standard File Preview can import
PICS, AIFF, PICT, and System 7 sound files.
- 1-bit dither: Playback performace of color movies has been significantly enhanced on black-and-white (1-
bit) displays. This is particularly useful on PowerBook computers.
- Sequence grabber dialogs: To provide for a more flexible and consistent user interface for configuring
capture devices, the sequence grabber provides a set of standard configuration dialogs. Support for
sound capture is also substantially improved.
- Text media handler: In addition to sound and video, QuickTime 1.5 has built-in support for text. The text
media handler is built using QuickTime's new Generic Media handler, which allows you to create your
own QuickTime data types.
- Standard compression: The Standard Image Compression dialog is now built into QuickTime. The user
can pan and zoom the test image within Standard Compression.
GUILLERMO A. ORTIZWhen I met Guillermo I was really young. The first thing I said to him was, "Are you my dad?"
Well, really I said something like "Waaaa!" As a matter of fact, I was a newborn. What I like about Guillermo is that we
are almost the same. We like the same food and we watch the same TV shows, like Star Trek and Nova . We like to play
the same sports, such as tennis and basketball, and we both like to read a lot -- lately we even read the same books. But
the one way we are most alike is that we love computers. Isn't that a weird coincidence? Another thing I like about
Guillermo is that he is really smart. He used to be a teacher, and having a teacher around the house is always useful. He
is always there to help me with stuff like math and science. He is also a great cook. The dinners he prepares for us on the
weekends are fit for a king! He is like my family's own personal four-star chef. The music Guillermo likes to listen to is the
Beatles, the Doors, Santana, and Cream. I like those groups too, but on our way to school we listen to rap. Guillermo is a
great guy and I am really glad to have him for a dad.
-- Guillermo A. Ortiz Jr., age 13 *
RECOMMENDED READINGThis article assumes a reasonable knowledge of QuickTime programming. For background information, see the QuickTime
developer notes, available from APDA as part of the QuickTime Developer's Kit v. 1.0 (#R0147LL/A). For an introduction
to QuickTime, see my article "QuickTime 1.0: 'You Oughta Be in Pictures'" in develop Issue 7.*
There are no guidelines (as of this writing) regarding ways to allow users to set the rate
of a movie; the solution implemented in TimeBaseSimple has not been approved by the User Interface gods. It's primitive,
but it works.*
The TimeBaseSimple shuttle control is a cool CDEF created by C. K. Haun, member emeritus of Developer Technical
Support. Its C source is included on the Developer CD Series disc.*
THANKS TO OUR TECHNICAL REVIEWERS Bill Guschwan, Peter Hoddie, David Van Brink*