Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Movie Time and Space
This chapter describes the functions of the movie toolbox that your application will use to manipulate the timebase and spatial characteristics of movies, tracks, and media.
Working With Movie Spatial Characteristics
The Movie Toolbox provides a number of functions that allow your application to determine and change the spatial characteristics of movies and tracks. Before using any of them, you should be familiar with the way in which the Movie Toolbox displays movies. Here are some tips for using these functions:
You can use the
GetMovieGWorldfunctions to work with a movie’s graphics world.
Your application can work with a movie’s matrix by calling the
SetMovieMatrixfunctions, and it can work with a track’s matrix with the
SetTrackMatrixfunctions. Then you can perform operations on matrices with the Movie Toolbox’s matrix functions described in Matrix Functions.
Certain functions affect the displayed movie and its tracks in the final display coordinate system. The
GetMovieGWorldfunctions let you work with a movie’s display destination. The
SetMovieBoxfunctions allow you to work with a movie’s boundary rectangle and its associated transformations. Alternatively, you can use the
SetMovieMatrixfunctions to work directly with a movie’s transformation matrix. The
GetMovieDisplayBoundsRgnfunction determines a movie’s boundary region at the current movie time. On the other hand, the
GetMovieSegmentDisplayBoundsRgnfunction determines a movie’s boundary region over a specified time segment. You can use the
SetMovieDisplayClipRgnfunctions to work with a movie’s display clipping region.
GetTrackSegmentDisplayBoundsRgnfunctions determine a track’s final boundary region. You can use the
SetTrackLayerfunctions to control the drawing order of tracks within a movie.
A number of functions affect a movie’s display boundaries before any display transformations. These functions operate in the movie’s display coordinate system. You can use the
SetMovieClipRgnfunctions to work with a movie’s clipping region; that is, the clipping region that is applied before the movie display transformation. Use the
GetMovieBoundsRgnfunction to determine a movie’s boundary region at the current movie time.
GetTrackMovieBoundsRgnfunction to work with a track’s boundary region after matrix transformations have placed the track into the movie’s display system. The
GetTrackMatrixfunctions let you define a track’s matrix transformations.
The Movie Toolbox provides several functions that affect a track’s display boundaries; these functions operate in the track’s display coordinate system before any other display transformations are applied. The
SetTrackDimensionsfunctions allow you to establish a track’s coordinate system and to establish a track’s source rectangle.
You can use the
GetTrackBoundsRgnfunction to determine a track’s boundary region. The
SetTrackClipRgnfunctions let you work with a track’s clipping region. You can use the
SetTrackMattefunctions to establish a track’s matte. The
DisposeMattefunction allows you to dispose of a matte once you are finished with it.
The Movie Toolbox provides a number of functions that allow you to work with transformation matrices. This section describes those functions. For descriptions of fixed-point and fixed-rectangle structures, see The Fixed-Point and Fixed-Rectangle Structures.
The Fixed-Point and Fixed-Rectangle Structures
The Movie Toolbox matrix functions provide two mechanisms for specifying points and rectangles. Some of the functions work with standard QuickDraw points and rectangles, which use integer values to identify coordinates. Others, such as the
TransformFixedRect function, work with points and rectangles whose coordinates are expressed as fixed-point numbers. By using fixed-point numbers in these points and rectangles, the Movie Toolbox can support a greater degree of precision when defining graphic objects.
FixedPoint data type defines a fixed point. The
FixedRect data type defines a fixed rectangle. Note that both of these structures define the x coordinate before the y coordinate. This is different from the standard QuickDraw structures.
Fixed x; /* point's x coordinate as fixed-point number */
Fixed y; /* point's y coordinate as fixed-point number */
typedef struct FixedPoint FixedPoint;
Defines the point's x coordinate as a fixed-point number.
Defines the point's y coordinate as a fixed-point number.
Fixed left; /* x coordinate of upper-left corner */
Fixed top; /* y coordinate of upper-left corner */
Fixed right; /* x coordinate of lower-right corner */
Fixed bottom; /* y coordinate of lower-right corner */
typedef struct FixedRect FixedRect;
Defines the x coordinate of the upper-left corner of the rectangle as a fixed-point number.
Defines the y coordinate of the upper-left corner of the rectangle as a fixed-point number.
Defines the x coordinate of the lower-right corner of the rectangle as a fixed-point number.
Defines the y coordinate of the lower-right corner of the rectangle as a fixed-point number.
Creating a Track Matte
Listing 1-1 provides an example of how to create a track matte. The
CreateTrackMatte function adds an uninitialized, 8-bit-deep, grayscale matte to a track. The
UpdateTrackMatte function draws a gray ramp rectangle around the edge of the matte and fills the center of the matte with black. (A ramp rectangle shades gradually from light to dark in smooth increments.)
Listing 1-1 Creating a track matte
void CreateTrackMatte (Track theTrack)
GetTrackDimensions (theTrack, &trackWidth, &trackHeight);
SetRect (&trackBox, 0, 0, FixRound (trackWidth),
grayCTab = GetCTable(40); /* 8 bit + 32 = 8 bit gray */
err = NewGWorld (&aGW, 8, &trackBox, grayCTab,
(GDHandle) nil, 0);
if (!err && (aGW != nil))
SetTrackMatte (theTrack, aGW->portPixMap);
void UpdateTrackMatte (Track theTrack)
theMovie = GetTrackMovie (theTrack);
trackMatte = GetTrackMatte (theTrack);
if (trackMatte == nil)
/* track doesn't have a matte, so give it one */
trackMatte = GetTrackMatte (theTrack);
if (trackMatte == nil)
GetGWorld (&savePort, &saveGDevice);
matteBox = (**trackMatte).bounds;
err = NewGWorld(&tempGW,
(**trackMatte).pmTable, (GDHandle) nil, 0);
if (err || (tempGW == nil)) return;
SetGWorld (tempGW, nil);
savePortPix = tempGW->portPixMap;
/* draw a gray ramp rectangle around the edge of the matte */
for (i = 0; i < 35; i++)
tempLong = 65536 - ((65536 / 35) * (long)i);
aColor.red = aColor.green = aColor.blue = tempLong;
InsetRect (&matteBox, 1, 1);
/* fill the center of the matte with black */
SetGWorld (savePort, saveGDevice);
SetTrackMatte (theTrack, trackMatte);
Working With Movie Time
Every QuickTime movie has its own time base. A movie’s time base allows all the tracks that make up the movie to be synchronized when the movie is played. The Movie Toolbox provides a number of functions that allow your application to determine and establish the time parameters of a movie:
You can use the
GetMovieTimeBasefunction to retrieve the time base for a movie.
You can work with a movie’s current time by calling the
You can work with a movie’s time scale by calling the
The Movie Toolbox can calculate the total duration of a movie. You can use the
GetMovieDurationfunction to retrieve a movie’s duration.
Your application can call the
SetMovieRateto work with a movie’s playback rate.
The next sections discuss those functions. Later sections in this chapter discuss the Movie Toolbox functions that allow you to work with the time parameters of tracks and media structures. For information about more functions that work with time, see Time Base Functions.
About Movie Time
At the most basic level, the Movie Toolbox allows you to process time based data. As such, the Movie Toolbox must provide a description of the time basis of that data as well as a definition of the context for evaluating that time basis. In QuickTime, a movie’s time basis is referred to as its time base. Geometrically, you can think of the time base as a vector that defines the direction and velocity of time for a movie. The context for a time base is called its time coordinate system. Essentially, the time coordinate system defines the axis on which the time base vector is plotted. The smallest single unit of time marked on that axis is defined by the time scale as the units per absolute second.
Time Coordinate Systems
A movie’s time coordinate system provides the context for evaluating the passage of time in the movie. If you think of the time coordinate system as defining an axis for measuring time, it is only natural that this axis would be marked with a scale that defines a basic unit of measurement. In QuickTime, that measurement system is called a time scale.
A QuickTime time scale defines the number of time units that pass each second in a given time coordinate system. A time coordinate system that has a time scale of 1 measures time in seconds. Similarly, a time coordinate system that has a time scale of 60 measures sixtieths of a second. In general, each time unit in a time coordinate system is equal to (1/time scale) seconds. Some common time scales are listed in Table 1-1.
Absolute time measured
Sixtieths of a second (Macintosh ticks)
Sound sampled at 22 kHz
Figure 1-1 shows a duration of two seconds in absolute time and equivalent durations in the common time scales listed in Table 1-1.
A particular point in time in a time coordinate system is represented using a time value. A time value is expressed in terms of the time scale of its time coordinate system. Without an appropriate time scale, a time value is meaningless. For example, in a time coordinate system with a time scale of 60, a time value of 180 translates to 3 seconds. Because all time coordinate systems tie back to absolute time (that is, time as we measure it in seconds), the Movie Toolbox can translate time values from one time coordinate system into another.
Time coordinate systems have a finite maximum duration that defines the maximum time value for a time coordinate system (the minimum time value is always 0). Note that as a QuickTime movie is edited, the duration changes.
As the value of the time scale increases (as the time unit for a coordinate system gets smaller in terms of absolute time), the maximum absolute time that can be represented in a time coordinate system decreases. For example, if a time value were represented as an unsigned 16-bit integer, its maximum value would be 65,535. In a time coordinate system with a time scale of 1, the maximum time value would represent 65,535 seconds. However, in a time coordinate system with a time scale of 5, the maximum time value would correspond to 13,107 seconds. Hence, a time coordinate system’s duration is limited by its time scale. QuickTime uses 32-bit and 64-bit quantities to represent time values, so you only need to worry about attaining a maximum absolute time in situations where a time coordinate system’s duration is very long or its time scale is very large.
A movie’s time base defines its current time value and the rate at which time passes for the movie. The rate specifies the speed and direction in which time travels in a movie. Negative rate values cause you to move backward through a movie’s data; positive values move forward. The time base also contains a reference to the clock that provides timing for the time base. QuickTime clocks are implemented as components that are managed by the Component Manager.
Time bases exist independently of any specific time coordinate system. However, time values extracted from a time base are meaningless without a time scale. Therefore, whenever you obtain a time value from a time base, you must specify the time scale of the time value result. The Movie Toolbox translates the time base’s time value into a value that is sensible in the specified time scale.
Figure 1-2 represents a time coordinate system and a time base geometrically. The time coordinate system is represented by a coordinate axis. In this example, the time coordinate system has a time scale of 2; that is, there are two time units in each second. The duration of this time coordinate system is 2 seconds, which is equivalent to 4 time units. An object’s time base is depicted by the large arrow under the axis that represents the time coordinate system. This time base has a current time value of 3 and a rate of 1. The starting time is a time value, expressed in the units of the time coordinate system.
Working With Track Time
The Movie Toolbox provides several functions that allow your application to determine and establish a track’s time parameters. A track uses the time base of the movie that contains the track; therefore there are no functions that work with a track’s time base or time scale. However, you can determine a track’s duration and its offset from the start of a movie.
All of the tracks in a movie use the movie’s time coordinate system. That is, the movie’s time scale defines the basic time unit for each of the movie’s tracks. Each track begins at the beginning of the movie, but the track’s data might not begin until some time value other than 0. This intervening time is represented by blank space. In an audio track the blank space translates to silence; in a video track the blank space generates no visual image. This blank space is the track offset. Each track has its own duration. This duration need not correspond to the duration of the movie. A movie duration always equals the maximum track duration. These functions help you work with track time:
You can use the
GetTrackDurationfunction to determine a track’s duration.
GetTrackOffsetfunctions enable you to work with a track’s offset from the start of the movie that contains it.
TrackTimeToMediaTimefunction lets you translate a track’s time to the corresponding time value of a media in the track.
Working With Media Time
The Movie Toolbox provides functions that allow your application to work with the time parameters of a media:
You can use the
GetMediaDurationfunction to determine a media’s duration.
SetMediaTimeScalelet you determine or establish a media’s time scale.
Time Base Functions
The Movie Toolbox provides a number of functions that allow you to work with time bases. A QuickTime time base defines the time coordinate system of a movie. However, you can also use QuickTime time bases to provide general timing services. This section describes the functions that allow your application to work with time bases.
This section has been divided into the following topics:
Creating and Disposing of Time Bases describes how to create and dispose of time bases and how to assign a time base to a movie
Working With Time Base Values discusses functions that allow your application to work with the contents of a time base
Time Structures describes a number of functions that allow you to convert times between time bases and to perform simple arithmetic on time values
Time Base Callback Functions describes the functions your application may use to condition a time base to invoke functions your application provides
Creating and Disposing of Time Bases
The following Movie Toolbox functions help your application create and dispose of time bases:
NewTimeBasefunction lets you create a new time base. You can use the
DisposeTimeBasefunction to dispose of a time base once you are finished with it.
Time bases rely on either a clock component or another time base for their time source. You can use the
SetTimeBaseMasterTimeBasefunction to cause one time base to be based on another time base. The
GetTimeBaseMasterTimeBaseallows you to determine the master time base of a given time base.
You can assign a clock component to a time base; that clock then acts as the master clock for the time base. You can use the
SetTimeBaseMasterClockfunction to assign a clock component to a time base. The
GetTimeBaseMasterClockfunction enables you to determine the clock component that is assigned to a time base. You can change the offset between a time base and its time source by calling the
You can set the time source of a movie by calling the
Working With Time Base Values
Every time base contains a rate, a start time, a stop time, a current time, and some status information. The Movie Toolbox provides a number of functions that allow your application to work with the contents of a time base. You can use these functions:
GetTimeBaseTimefunction lets you retrieve the current time value of a time base. You can set the current time value by calling the
SetTimeBaseTimefunction; this function requires you to provide a time structure. Alternatively, you can set the current time based on a time value by calling the
You can determine the rate of a time base by calling the
GetTimeBaseRatefunction. You can set the rate of a time base by calling the
SetTimeBaseRatefunction. You can determine the effective rate of a specified time base (relative to the master time base to which it is subordinate) by calling the
You can retrieve the start time of a time base by calling the
GetTimeBaseStartTimefunction. You can set the start time of a time base by calling the
SetTimeBaseStartTimefunction. Similarly, you can use the
SetTimeBaseStopTimefunctions to work with the stop time of a time base.
The Movie Toolbox also provides functions that allow you to work with the status information of a time base:
GetTimeBaseStatusfunction allows you to read the current status of a time base.
GetTimeBaseFlagsfunction helps you obtain the control flags of a time base. You can set these flags by calling the
The Movie Toolbox provides a number of functions that allow you to work with time structures:
You can use the
ConvertTimefunction to convert a time you obtain from one time base into a time that is relative to another time base. Similarly, you can use the
ConvertTimeScalefunction to convert a time from one time scale to another.
You can add two times by calling the
AddTimefunction; you can subtract two times with the
All of these functions work with time structures. You can use time structures to represent either time values or durations. Time values specify a point in time, relative to a given time base. Durations specify a span of time, relative to a given time scale. Durations are represented by time structures that have the time base set to 0 (that is, the
base field in the time structure is set to
The TimeRecord Structure
Many time management functions require that you place a time specification in a data structure called a
CompTimeValue value; /* time value (duration or absolute) */
TimeScale scale; /* units per second */
TimeBase base; /* reference to the time base */
typedef struct TimeRecord TimeRecord;
Contains the time value. The time value defines either a duration or an absolute time by specifying the corresponding number of units of time. For durations, this is the number of time units in the period. For an absolute time, this is the number of time units since the beginning of the time coordinate system. The unit for this value is defined by the scale field. The time value is expressed as a
Contains the time scale. This field specifies the number of units of time that pass each second. If you specify a value of 0, the time base uses its natural time scale.
Contains a reference to the time base. You obtain a time base by calling the Movie Toolbox's
Large Time Values
You can specify the time value in a time structure as a 64-bit integer value as follows:
typedef Int64 CompTimeValue;
The Movie Toolbox uses this format so that extremely large time values can be represented. The
Int64 data type defines the format of these signed 64-bit integers.
long hi; /* high-order 32 bits-value field in time structure */
long lo; /* low-order 32 bits-value field in time structure */
typedef struct Int64 Int64;
Contains the high-order 32 bits of the value. The high-order bit represents the sign of the 64-bit integer.
Contains the low-order 32 bits of the value.
Time Base Callback Functions
If your application uses QuickTime time bases, it may define callback functions that are associated with a specific time base. Your application can then use these callback functions to perform activities that are triggered by temporal events, such as a certain time being reached or a specified rate being achieved. The time base functions of the Movie Toolbox interact with clock components to schedule the invocation of these callback functions; clock components are responsible for invoking the callback function at its scheduled time. Your application can use the functions described in this section to establish your own callback function and to schedule callback events.
You can define three types of callback events. These types are distinguished by the nature of the temporal event that triggers the Movie Toolbox to call your function. The three types are
events that are triggered at a specified time
events that are triggered when the rate reaches a specified value
events that are triggered when the time value of a time base changes by an amount different from the time base’s rate.
Use these functions to work with time base callbacks:
You specify a callback event’s type when you define the callback event, using the
You specify whether your event can occur at interrupt time when you define the callback event, using the
NewCallBackfunction. Your function is called closer to the triggering event at interrupt time, but it is subject to all the restrictions of interrupt functions (for example, your callback function cannot cause memory to be moved). If your function is not called at interrupt time, you are free of these restrictions; but your function may be called later, because the invocation is delayed to avoid interrupt time.
NewCallBackfunction allocates the memory to support a callback event. When you are done with the callback event, you dispose of it by calling the
You schedule a callback event by calling the
CancelCallBackfunction to unschedule a callback event.
You can retrieve the time base of a callback event by calling the
You can obtain the type of a callback event by calling the
Time and Space Function Summary
Here is a summary of the Movie Toolbox functions you can use to manage movie time and spatial characteristics.
Managing Movie Space
The Movie Toolbox contains a number of functions that your application can use to determine or change the spatial display characteristics of movies and tracks. These functions affect the movie’s graphics world, its matrix, the final display coordinate system, and the display boundaries. They include
Working With Matrices
Several Movie Toolbox functions allow you to manipulate transformation matrices.
Managing Movie Time
Several functions are used to work with a movie’s time parameters. Included are functions for retrieving the time base, working with the current movie time, working with the time scale, calculating the movie’s duration, and getting and setting the playback rate.
Managing Track Time
Several functions work with a track’s time parameters. All tracks share the movie’s time base, but each track contains its own offset and duration. A function is also provided to translate track time into a value appropriate to the track’s media.
Managing Media Time
Three functions work with a media’s time parameters. Each media has its own time scale and duration.
Finding Interesting Times
You can call Movie Toolbox functions to search a movie, track or media for a particular sample, such as a keyframe. The functions return the time and duration of the next sample that meets the search criteria.
Time Base Management
Various Movie Toolbox functions work with time bases. A QuickTime time base defines the time coordinate system for a movie. It can also be used to provide general timing services.
Most of these functions are discussed in the preceding sections of this chapter.