Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions That Modify Movie Properties / Finding Interesting Times

GetMovieNextInterestingTime

The GetMovieNextInterestingTime function searches for times of interest in a movie. This function examines only the movie's enabled tracks.

pascal void GetMovieNextInterestingTime (Movie theMovie, 
                                 short interestingTimeFlags, 
                                 short numMediaTypes, 
                                 const OSType *whichMediaTypes,
                                 TimeValue time, Fixed rate,
                                 TimeValue *interestingTime,
                                 TimeValue *interestingDuration);

theMovie

Specifies the movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle (described on page 2-80, page 2-76, and page 2-78, respectively).

interestingTimeFlags

Specifies the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, nextTimeTrackEdit and nextTimeSyncSample flags to 1. The following flags are available (set unused flags to 0):

nextTimeMediaSample

Searches for the next sample in the movie's media. Set this flag to 1 to search for the next sample.

nextTimeMediaEdit

Searches for the next group of samples in the movie's media. Set this flag to 1 to search for the next group of samples.

nextTimeTrackEdit

Searches for the media sample that corresponds to the next entry in a track's media edit list. The end of the track is considered an empty edit. Set this flag to 1 to search for the next track edit.

nextTimeSyncSample

Searches for the next sync sample in the movie's media. Set this flag to 1 to search for the next sync sample.

Sync samples do not rely on preceding frames for content. Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample.

nextTimeEdgeOK

Instructs the Movie Toolbox that you are willing to receive information about elements that begin or end at the time specified by the time parameter. Set this flag to 1 to accept this information.

This flag is especially useful at the beginning or end of a movie. The function returns valid information about the beginning and end of the movie.

nextTimeIgnoreActiveSegment

Instructs the Movie Toolbox to look outside of the active segment for samples that meet the search criteria. Set this flag to 1 to search outside of the active segment.

numMediaTypes

Specifies the number of media types in the table referred to by the whichMediaType parameter. Set this parameter to 0 to search all media types.

whichMediaTypes

Contains a pointer to an array of media types. You can use this parameter to limit the search to a specified set of media types. Each entry in the table referred to by this parameter identifies a media type to be included in the search. You use the numMediaTypes parameter to indicate the number of entries in the table. Set this parameter to nil to search all media types.

VisualMediaCharacteristic 'eyes'
Instructs the Movie Toolbox to search all tracks that have spatial bounds.

AudioMediaCharacteristic 'ears'
Instructs the Movie Toolbox to search all tracks that play sound.

time

Specifies a time value that establishes the starting point for the search. This time value must be expressed in the movie's time scale.

rate

Contains the search direction. Negative values cause the Movie Toolbox to search backward from the starting point specified in the time parameter. Other values cause a forward search.

interestingTime

Contains a pointer to a time value. The Movie Toolbox returns the first time value it finds that meets the search criteria specified in the flags parameter. This time value is in the movie's time scale.

If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1.

If you are not interested in this information, set this parameter to nil.

interestingDuration

Contains a pointer to a time value. The Movie Toolbox returns the duration of the interesting time. This time value is in the movie's time coordinate system. Set this parameter to nil if you do not want this information--in this case, the function works more quickly.

DESCRIPTION

You can use the GetMovieNextInterestingTime function to step through the frames of a movie one by one. If no tracks match the media types, the invalidMedia error is returned.

ERROR CODES

invalidMedia	-2008	This media is corrupted or invalid
invalidTrack	-2009	This track is corrupted or invalid
invalidMovie	-2010	This movie is corrupted or invalid
invalidTime	-2015	This time value is invalid