Matrix Functions

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.

The 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.

struct FixedPoint

{

    Fixed x;        /* point's x coordinate as fixed-point number */

    Fixed y;        /* point's y coordinate as fixed-point number */

};

typedef struct FixedPoint FixedPoint;

struct FixedRect

{

    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;

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)

{

    QDErr err;

    GWorldPtr aGW;

    Rect trackBox;

    Fixed trackHeight;

    Fixed trackWidth;

    CTabHandle grayCTab;

    GetTrackDimensions (theTrack, &trackWidth, &trackHeight);

    SetRect (&trackBox, 0, 0, FixRound (trackWidth),

                 FixRound (trackHeight));

    grayCTab = GetCTable(40);    /* 8 bit + 32 = 8 bit gray */

    err = NewGWorld (&aGW, 8, &trackBox, grayCTab,

                         (GDHandle) nil, 0);

    DisposeCTable (grayCTab);

    if (!err && (aGW != nil))

    {

        SetTrackMatte (theTrack, aGW->portPixMap);

        DisposeGWorld (aGW);

    }

}

void UpdateTrackMatte (Track theTrack)

{

    OSErr err;

    PixMapHandle trackMatte;

    PixMapHandle savePortPix;

    Movie       theMovie;

    GWorldPtr tempGW;

    CGrafPtr savePort;

    GDHandle saveGDevice;

    Rect        matteBox;

    short       i;

    theMovie = GetTrackMovie (theTrack);

    trackMatte = GetTrackMatte (theTrack);

    if (trackMatte == nil)

    {

        /* track doesn't have a matte, so give it one */

        CreateTrackMatte (theTrack);

        trackMatte = GetTrackMatte (theTrack);

        if (trackMatte == nil)

            return;

    }

    GetGWorld (&savePort, &saveGDevice);

    matteBox = (**trackMatte).bounds;

    err = NewGWorld(&tempGW,

                       (**trackMatte).pixelSize, &matteBox,

                       (**trackMatte).pmTable, (GDHandle) nil, 0);

    if (err || (tempGW == nil)) return;

    SetGWorld (tempGW, nil);

    savePortPix = tempGW->portPixMap;

    LockPixels (trackMatte);

    SetPortPix (trackMatte);

    /* draw a gray ramp rectangle around the edge of the matte */

    for (i = 0; i < 35; i++)

    {

        RGBColor aColor;

        long        tempLong;

        tempLong = 65536 - ((65536 / 35) * (long)i);

        aColor.red = aColor.green = aColor.blue = tempLong;

        RGBForeColor(&aColor);

        FrameRect (&matteBox);

        InsetRect (&matteBox, 1, 1);

    }

    /* fill the center of the matte with black */

    ForeColor (blackColor);

    PaintRect (&matteBox);

    SetPortPix (savePortPix);

    SetGWorld (savePort, saveGDevice);

    DisposeGWorld (tempGW);

    UnlockPixels (trackMatte);

    SetTrackMatte (theTrack, trackMatte);

    DisposeMatte (trackMatte);

}

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.

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.

Time Bases

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 GetTrackDuration function to determine a track’s duration.

• The SetTrackOffset and GetTrackOffset functions enable you to work with a track’s offset from the start of the movie that contains it.

• The TrackTimeToMediaTime function 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 GetMediaDuration function to determine a media’s duration.

• The GetMediaTimeScale and SetMediaTimeScale let 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:

• The NewTimeBase function lets you create a new time base. You can use the DisposeTimeBase function 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 SetTimeBaseMasterTimeBase function to cause one time base to be based on another time base. The GetTimeBaseMasterTimeBase allows 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 SetTimeBaseMasterClock function to assign a clock component to a time base. The GetTimeBaseMasterClock function 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 SetTimeBaseZero function.

• You can set the time source of a movie by calling the SetMovieMasterTimeBase and SetMovieMasterClock functions.

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:

• The GetTimeBaseTime function lets you retrieve the current time value of a time base. You can set the current time value by calling the SetTimeBaseTime function; this function requires you to provide a time structure. Alternatively, you can set the current time based on a time value by calling the SetTimeBaseValue function.

• You can determine the rate of a time base by calling the GetTimeBaseRate function. You can set the rate of a time base by calling the SetTimeBaseRate function. 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 GetTimeBaseEffectiveRate function.

• You can retrieve the start time of a time base by calling the GetTimeBaseStartTime function. You can set the start time of a time base by calling the SetTimeBaseStartTime function. Similarly, you can use the GetTimeBaseStopTime and SetTimeBaseStopTime functions 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:

• The GetTimeBaseStatus function allows you to read the current status of a time base.

• The GetTimeBaseFlags function helps you obtain the control flags of a time base. You can set these flags by calling the SetTimeBaseFlags function.

The TimeRecord Structure

Many time management functions require that you place a time specification in a data structure called a TimeRecord.

struct TimeRecord

{

    CompTimeValue       value;      /* time value (duration or absolute) */

    TimeScale       scale;          /* units per second */

    TimeBase        base;           /* reference to the time base */

};

typedef struct TimeRecord TimeRecord;

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.

struct Int64

{

    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;

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

• SetTrackGWorld

• SetMovieGWorld

• GetMovieGWorld

• SetMovieBox

• GetMovieBox

• GetMovieDisplayBoundsRgn

• GetMovieSegmentDisplayBoundsRgn

• SetMovieDisplayClipRgn

• GetMovieDisplayClipRgn

• GetTrackSegmentDisplayBoundsRgn

• SetTrackLayer

• GetTrackLayer

• SetMovieMatrix

• GetMovieMatrix

• GetMovieBoundsRgn

• GetTrackMovieBoundsRgn

• GetMovieClipRgn

• SetTrackMatrix

• GetTrackMatrix

• GetTrackBoundsRgn

• SetTrackDimensions

• GetTrackDimensions

• SetTrackClipRgn

• GetTrackClipRgn

• SetTrackMatte

• GetTrackMatte

• DisposeMatte

• SetMovieColorTable

• GetMovieColorTable

Working With Matrices

Several Movie Toolbox functions allow you to manipulate transformation matrices.

• SetIdentityMatrix

• GetMatrixType

• CopyMatrix

• EqualMatrix

• TranslateMatrix

• ScaleMatrix

• RotateMatrix

• SkewMatrix

• ConcatMatrix

• InverseMatrix

• TransformPoints

• TransformFixedPoints

• TransformRect

• TransformFixedRect

• TransformRgn

• RectMatrix

• MapMatrix

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.

• GetMovieDuration

• SetMovieTimeValue

• SetMovieTime

• GetMovieTime

• SetMovieRate

• GetMovieRate

• SetMovieTimeScale

• GetMovieTimeScale

• GetMovieTimeBase

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.

• GetTrackDuration

• SetTrackOffset

• GetTrackOffset

• TrackTimeToMediaTime

Managing Media Time

Three functions work with a media’s time parameters. Each media has its own time scale and duration.

• GetMediaDuration

• SetMediaTimeScale

• GetMediaTimeScale

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.

• GetMovieNextInterestingTime

• GetTrackNextInterestingTime

• GetMediaNextInterestingTime

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.

• Creating and Disposing of Time Bases

  • NewTimeBase

  • DisposeTimeBase

  • SetMovieMasterClock

  • SetMovieMasterTimeBase

  • SetTimeBaseMasterClock

  • GetTimeBaseMasterClock

  • SetTimeBaseMasterTimeBase

  • GetTimeBaseMasterTimeBase

  • SetTimeBaseZero

• Working With Time Base Values

  • SetTimeBaseTime

  • SetTimeBaseValue

  • SetTimeBaseRate

  • GetTimeBaseRate

  • GetTimeBaseEffectiveRate

  • SetTimeBaseStartTime

  • GetTimeBaseStartTime

  • SetTimeBaseStopTime

  • GetTimeBaseStopTime

  • SetTimeBaseFlags

  • GetTimeBaseFlags

  • GetTimeBaseStatus

• Time Structures

  • AddTime

  • SubtractTime

  • ConvertTime

  • ConvertTimeScale

• Time Base Callback Functions

  • NewCallBack

  • CallMeWhen

  • CancelCallBack

  • DisposeCallBack

  • GetCallBackTimeBase

  • GetCallBackType

Most of these functions are discussed in the preceding sections of this chapter.