Inside Macintosh: QuickTime /

Chapter 2 - Movie Toolbox / Movie Toolbox Reference

Functions for Getting and Playing Movies / Movie Functions

NewMovieFromFile

The NewMovieFromFile function creates a movie in memory from a resource that is stored in a movie file. Your application specifies the movie file with the file reference number that was returned by the OpenMovieFile function, which is described on page 2-86. Your application can use the NewMovieFromHandle function, described in the next section, to load a movie from a handle. Once you have opened a movie file and loaded a movie, your application can proceed to work with the movie.

pascal OSErr NewMovieFromFile (Movie *theMovie, short resRefNum, 
                              short *resId, 
                              StringPtr resName, 
                              short newMovieFlags, 
                              Boolean *dataRefWasChanged);

theMovie

Contains a pointer to a field that is to receive the new movie's identifier. If the function cannot load the movie, the returned identifier is set to nil.

resRefNum

Identifies the movie file from which the movie is to be loaded. Your application obtains this value from the OpenMovieFile function, described on page 2-86.

resId

Contains a pointer to a field that specifies the resource containing the movie data that is to be loaded. If the field referred to by the resId parameter is set to 0, the Movie Toolbox loads the first movie resource it finds in the specified file. The toolbox then returns the movie's resource ID number in the field referred to by the resId parameter. The following enumerated constant is available:

movieInDataForkResID

Forces the movie to come out of the data fork. If the resource was stored in the file's data fork, the Movie Toolbox sets the returned value to movieInDataForkResID (-1). In this case, you cannot add a movie resource to the file unless you create a resource fork in the movie file.

If the resId parameter is set to nil, the Movie Toolbox loads the first movie resource it finds in the specified file and does not return that resource's ID number.

resName

Points to a character string that is to receive the name of the movie resource that is loaded. If you set the resName parameter to nil, the toolbox does not return the resource name.

newMovieFlags

Controls the operation of the NewMovieFromFile function. The following flags are available (be sure to set unused flags to 0):

newMovieActive

Controls whether the new movie is active. Set this flag to 1 to make the new movie active. You can make a movie active or inactive by calling the SetMovieActive function, which is described on page 2-131.

newMovieDontResolveDataRefs

Controls how completely the Movie Toolbox resolves data references in the movie resource. If you set this flag to 0, the toolbox tries to completely resolve all data references in the resource. This may involve searching for files on multiple volumes. If you set this flag to 1, the Movie Toolbox only looks in the specified file.

If the Movie Toolbox cannot completely resolve all the data references, it still returns a valid movie identifier. In this case, the Movie Toolbox also sets the current error value to couldNotResolveDataRef.

newMovieDontAskUnresolvedDataRefs

Controls whether the Movie Toolbox asks the user to locate files. If you set this flag to 0, the Movie Toolbox asks the user to locate files that it cannot find. If the Movie Toolbox cannot locate a file even with the user's help, the function returns a valid movie identifier and sets the current error value to couldNotResolveDataRef.

newMovieDontAutoAlternate

Controls whether the Movie Toolbox automatically selects enabled tracks from alternate track groups. If you set this flag to 1, the Movie Toolbox does not automatically select tracks for the movie--you must enable tracks yourself.

dataRefWasChanged

Contains a pointer to a Boolean value. The Movie Toolbox sets the Boolean to indicate whether it had to change any data references while resolving them. The toolbox sets the Boolean value to true if any references were changed. Use the UpdateMovieResource function (described on page 2-91) to preserve these changes.

Set the dataRefWasChanged parameter to nil if you do not want to receive this information. See "Creating Tracks and Media Structures" beginning on page 2-136 for more information about data references.

DESCRIPTION

The Movie Toolbox sets many movie characteristics to default values. If you want to change these defaults, your application must call other Movie Toolbox functions. For example, the Movie Toolbox sets the movie's graphics world to the one that is active when you call NewMovieFromFile. To change the graphics world for the new movie, your application should use the SetMovieGWorld function, which is described on page 2-145.

SPECIAL CONSIDERATIONS

The Movie Toolbox automatically sets the movie's graphics world based upon the current graphics port. Be sure that your application's graphics world is valid before you call this function.

ERROR CODES

badImageDescription	-2001	Problem with an image description
badPublicMovieAtom	-2002	Movie file corrupted
cantFindHandler	-2003	Cannot locate a handler
cantOpenHandler	-2004	Cannot open a handler

File Manager errors
Memory Manager errors
Resource Manager errors