Legacy Mac OS X Reference Library Apple Developer Connection

Movie Toolkit Reference

Framework
Frameworks/QuickTime.framework
Declared in
Files.h
MacTypes.h
Movies.h

Overview

The QuickTime Movie Toolkit helps your application construct movies, including determining what types of media to present, where movie data are located, when and how to present each data sample, and how to layer, arrange, and composite multiple movie elements.

Functions by Task

Associating Movies With Controllers

Audio Conversion and Extraction

Copying Existing Atoms

Creating and Disposing of Atom Containers

Creating and Manipulating Sprites

Creating New Atoms

Enhancing Movie Playback Performance

Error Functions

Finding and Adding Samples

Finding Interesting Times

High-Level Download Control

High-Level Effects Functions

High-Level Movie Editing Functions

Low-Level Download Control

Metering Sound Level and Frequency

Modifying Atoms

Movie Functions

Movie Posters and Movie Previews

Movies and Your Event Loop

Registering and Unregistering Access Keys

Removing Atoms From an Atom Container

Retrieving Access Keys

Retrieving Atoms and Atom Data

Saving Movies

Setting Sound Parameters

Tween Component Requirements

Using the Full Screen

Working With Alternate Tracks

Working With Data References

Working With Media Handler Properties

Working With Movie Restrictions

Working With Movie Spatial Characteristics

Working With Progress and Cover Functions

Working With Sprite Worlds

Working With User Data

Supporting Functions

Functions

AddMediaDataRef

Adds a data reference to a media.

OSErr AddMediaDataRef (
   Media theMedia,
   short *index,
   Handle dataRef,
   OSType dataRefType
);
Parameters
theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

index

A pointer to a short integer. The Movie Toolbox returns the index value that is assigned to the new data reference. Your application can use this index to identify the reference to other Movie Toolbox functions, such as GetMediaDataRef. If the Movie Toolbox cannot add the data reference to the media, it sets the returned index value to 0.

dataRef

The data reference. This parameter contains a handle to the information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter.

dataRefType

The type of data reference. If the data reference is an alias, you must set this parameter to rAliasType.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

AddMovieExecuteWiredActionsProc

Lets you add a callback to a movie to execute wired actions.

OSErr AddMovieExecuteWiredActionsProc (
   Movie theMovie,
   MovieExecuteWiredActionsUPP proc,
   void *refCon
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

proc

A callback function, as described in MovieExecuteWiredActionsProc.

refCon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your function needs.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
Movies.h

AddMovieResource

Adds a movie resource to a specified resource file.

OSErr AddMovieResource (
   Movie theMovie,
   short resRefNum,
   short *resId,
   ConstStr255Param resName
);
Parameters
theMovie

The movie you wish to add to the movie file. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

resRefNum

Identifies the movie file to which the resource is to be added. Your application obtains this value from the OpenMovieFile function.

resId

A pointer to a field that contains the resource ID number for the new resource. If the field referred to by resId is set to 0, the Movie Toolbox assigns a unique resource ID number to the new resource. The toolbox then returns the movie's resource ID number in the field referred to by the resId parameter. AddMovieResource assigns resource ID numbers sequentially, starting at 128. If resId is set to NIL, the Movie Toolbox assigns a unique resource ID number to the new resource and does not return that resource's ID value. Set resId to movieInDataForkResID to add the new resource to the movie file's data fork (see below). See these constants:

  • movieInDataForkResID

resName

Points to a character string that contains the name of the movie resource. If you set resName to NIL, the toolbox creates an unnamed resource.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function adds the movie to the file, effectively saving any changes you have made to the movie. To use this function with single-fork movie files, pass movieInDataForkResID as the resId parameter. After updating the movie file, AddMovieResource clears the movie changed flag, indicating that the movie has not been changed.

// AddMovieResource coding example
// See "Discovering QuickTime," page 243
void CreateMyCoolMovie (void)
{
    StandardFileReply   sfr;
    Movie               movie =NIL;
    FSSpec              fss;
    short               nFileRefNum =0;
    short               nResID =movieInDataForkResID;
    StandardPutFile("\pEnter movie file name:", "\puntitled.mov", &sfr);
    if (!sfr.sfGood)
        return;
    CreateMovieFile(&sfr.sfFile,
                    FOUR_CHAR_CODE('TVOD'),
                    smCurrentScript,
                    createMovieFileDeleteCurFile |
                     createMovieFileDontCreateResFile,
                    &nFileRefNum,
                    &movie);
    CreateMyVideoTrack(movie);      // See next section
    CreateMySoundTrack(movie);      // See next section
    AddMovieResource(movie, nFileRefNum, &nResID, NIL);
    if (nFileRefNum !=0)
        CloseMovieFile(nFileRefNum);
    DisposeMovie(movie);
}
Version Notes

Introduced in QuickTime 3 or earlier. Superseded in QuickTime 6 by AddMovieToStorage.

Availability
Related Sample Code
Declared In
Movies.h

AddMovieToStorage

Adds a movie to a storage container that was created by CreateMovieStorage.

OSErr AddMovieToStorage (
   Movie theMovie,
   DataHandler dh
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

dh

The data handler component that was returned by CreateMovieStorage.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function calls PutMovieIntoStorage internally. If you are writing a custom data handler, make sure it implements DataHGetDataRef. Also implement DataHScheduleData64 and DataHGetFileSize64, or DataHScheduleData and DataHGetFileSize if the data handler does not support 64-bit file offsets, plus DataHWrite64, or DataHWrite if it does not support 64-bit offsets.

Version Notes

Introduced in QuickTime 6. Supersedes AddMovieResource.

Availability
Related Sample Code
Declared In
Movies.h

AddSoundDescriptionExtension

Adds an extension to a SoundDescription structure.

OSErr AddSoundDescriptionExtension (
   SoundDescriptionHandle desc,
   Handle extension,
   OSType idType
);
Parameters
desc

A handle to the SoundDescription structure to add the extension to.

extension

The handle containing the extension data.

idType

A four-byte signature identifying the type of data being added to the SoundDescription.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Two extensions are defined to the SoundDescription record. The first is the slope, intercept, minClip, and maxClip parameters for audio, represented as an atom of type 'flap'. The second extension is the ability to store data specific to a given audio codec, using a SoundDescriptionV1 structure.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

AddUserData

Adds an item to a user data list.

OSErr AddUserData (
   UserData theUserData,
   Handle data,
   OSType udType
);
Parameters
theUserData

The user data list for this operation. You obtain this item reference by calling GetMovieUserData, GetTrackUserData, or GetMediaUserData.

data

A handle to the data to be added to the user data list.

udType

The type that is to be assigned to the new item.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

You specify the user data list, the data to be added, and the data's type value.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

AddUserDataText

Places language-tagged text into an item in a user data list.

OSErr AddUserDataText (
   UserData theUserData,
   Handle data,
   OSType udType,
   long index,
   short itlRegionTag
);
Parameters
theUserData

The user data list for this operation. You obtain this list reference by calling GetMovieUserData, GetTrackUserData, or GetMediaUserData.

data

A handle to the data to be added to the user data list.

udType

The type that is to be assigned to the new item.

index

The item to which the text is to be added. This parameter must specify an item in the user data list identified by theUserData.

itlRegionTag

The region code of the text to be added. If there is already text with this region code in the item, the function replaces the existing text with the data specified by the data parameter. See Inside Macintosh: Text for more information about language and region codes.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

You specify the user data list and item, the data to be added, the data's type value, and the language code of the data.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

AttachMovieToCurrentThread

Attaches a movie to the current thread.

OSErr AttachMovieToCurrentThread (
   Movie m
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

See Error Codes in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

BeginFullScreen

Begins full-screen mode for a specified graphics device.

OSErr BeginFullScreen (
   Ptr *restoreState,
   GDHandle whichGD,
   short *desiredWidth,
   short *desiredHeight,
   WindowRef *newWindow,
   RGBColor *eraseColor,
   long flags
);
Parameters
restoreState

On exit, a pointer to a block of private state data that contains information on how to return from full-screen mode. This value is passed to EndFullScreen to enable it to return the monitor to its previous state.

whichGD

A handle to the graphics device to put into full-screen mode. Set this parameter to NIL to select the main screen.

desiredWidth

On entry, a pointer to a short integer that contains the desired width, in pixels, of the images to be displayed. On exit, that short integer is set to the actual number of pixels that can be displayed horizontally. Set this parameter to 0 to leave the width of the display unchanged.

desiredHeight

On entry, a pointer to a short integer that contains the desired height, in pixels, of the images to be displayed. On exit, that short integer is set to the actual number of pixels that can be displayed vertically. Set this parameter to 0 to leave the height of the display unchanged.

newWindow

On entry, a window-creation value. If this parameter is NIL, no window is created for you. If this parameter has any other value, BeginFullScreen creates a new window that is large enough to fill the entire screen and returns a pointer to that window in this parameter. You should not dispose of that window yourself; instead, EndFullScreen will do so.

eraseColor

The color to use when erasing the full-screen window created by BeginFullScreen if newWindow is not NIL on entry. If this parameter is NIL, BeginFullScreen uses black when initially erasing the window's content area.

flags

A set of bit flags (see below) that control certain aspects of the full-screen mode. See these constants:

  • fullScreenHideCursor

  • fullScreenAllowEvents

  • fullScreenDontChangeMenuBar

  • fullScreenPreflightSize

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function returns, in the restoreState parameter, a pointer to a block of private state information that indicates how to return from full-screen mode. You pass that pointer as a parameter to the EndFullScreen function. The following sample code contains functions that illustrate how to play a QuickTime movie full screen. It prompts the user for a movie, opens that movie, configures it to play full screen, associates a movie controller, and lets the controller handle events. Your application would call QTFullScreen_EventLoopAction in its event loop (on the Mac OS) or when it gets idle events (on Windows).

enum {
    fullScreenHideCursor            =1L << 0,
    fullScreenAllowEvents           =1L << 1,
    fullScreenDontChangeMenuBar     =1L << 2,
    fullScreenPreflightSize         =1L << 3
};
// QTFullScreen_PlayOnFullScreen
// Prompt the user for a movie and play it full screen.
OSErr QTFullScreen_PlayOnFullScreen (void)
{
    FSSpec              myFSSpec;
    Movie               myMovie =NIL;
    short               myRefNum =0;
    SFTypeList          myTypeList ={MovieFileType, 0, 0, 0};
    StandardFileReply   myReply;
    long                myFlags =fullScreenDontChangeMenuBar
                                                 | fullScreenAllowEvents;
    OSErr               myErr =noErr;
 
    StandardGetFilePreview(NIL, 1, myTypeList, &myReply);
    if (!myReply.sfGood)
        goto bail;
 
    // make an FSSpec record
    FSMakeFSSpec(myReply.sfFile.vRefNum, myReply.sfFile.parID,
                                          myReply.sfFile.name, &myFSSpec);
    myErr =OpenMovieFile(&myFSSpec, &myRefNum, fsRdPerm);
    if (myErr !=noErr)
        goto bail;
    // now fetch the first movie from the file
    myErr =NewMovieFromFile(&myMovie, myRefNum, NIL, NIL,
                                                    newMovieActive, NIL);
    if (myErr !=noErr)
        goto bail;
 
    CloseMovieFile(myRefNum);
    // set up for full-screen display
    myErr =BeginFullScreen(&gRestoreState, NIL, 0, 0,
                                       &gFullScreenWindow, NIL, myFlags);
#if TARGET_OS_WIN32
    // on Windows, set a window procedure for the new window
    // and associate a port with that window
    QTMLSetWindowWndProc(gFullScreenWindow, QTFullScreen_HandleMessages);
    CreatePortAssociation(GetPortNativeWindow(gFullScreenWindow), NIL, 0L);
#endif
    SetMovieGWorld(myMovie, (CGrafPtr)gFullScreenWindow,
                            GetGWorldDevice((CGrafPtr)gFullScreenWindow));
    SetMovieBox(myMovie, &gFullScreenWindow->
portRect);
    // create the movie controller
    gMC =NewMovieController(myMovie, &gFullScreenWindow->
portRect, 0);
Version Notes

The Macintosh human interface guidelines suggest that the menu bar must always be present, and that information must always appear in windows. However, many multimedia applications have chosen to change the look and feel of the interface based on their needs. The number of details to keep track of when doing this continues to increase. To help solve this problem, QuickTime 2.1 added functions to put a graphics device into full screen mode. The key elements to displaying full screen movies are the calls BeginFullScreen and EndFullScreen, introduced in QuickTime 2.5.

Availability
Related Sample Code
Declared In
Movies.h

CanQuickTimeOpenDataRef

Determines whether referenced data can be opened using a graphics importer or opened in place as a movie.

OSErr CanQuickTimeOpenDataRef (
   Handle dataRef,
   OSType dataRefType,
   Boolean *outCanOpenWithGraphicsImporter,
   Boolean *outCanOpenAsMovie,
   Boolean *outPreferGraphicsImporter,
   UInt32 inFlags
);
Parameters
dataRef

A handle to the referenced data.

dataRefType

The type of data reference pointed to by dataRef; see Data References.

outCanOpenWithGraphicsImporter

Points to a Boolean that will be set to TRUE if the file can be opened using a graphics importer and FALSE otherwise. If you do not want this information, pass NIL.

outCanOpenAsMovie

Points to a Boolean that will be set to TRUE if the file can be opened as a movie and FALSE otherwise. If you do not want this information, pass NIL.

outPreferGraphicsImporter

Points to a boolean which will be set to true if the file can be opened using a graphics importer and opened as a movie, but, other factors being equal, QuickTime prefers a graphics importer. For example, QuickTime recommends using a graphics importer for single-frame GIF files and opening as a movie for multiple-frame GIF files. If you do not want this information, pass NIL. Passing a valid pointer disables the kQTDontUseDataToFindImporter and kQTDontLookForMovieImporterIfGraphicsImporterFound flags, if set.

inFlags

Flags (see below) that modify search behavior. Pass 0 for default behavior. See these constants:

  • kQTDontUseDataToFindImporter

  • kQTDontLookForMovieImporterIfGraphicsImporterFound

  • kQTAllowOpeningStillImagesAsMovies

  • kQTAllowImportersThatWouldCreateNewFile

  • kQTAllowAggressiveImporters

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function determines whether QuickTime can open a given area of data. You should pass NIL in parameters that do not interest you, since that will allow QuickTime to perform a faster determination.

Version Notes

Introduced in QuickTime 5.

Availability
Related Sample Code
Declared In
Movies.h

CanQuickTimeOpenFile

Determines whether a file can be opened using a graphics importer or opened in place as a movie.

OSErr CanQuickTimeOpenFile (
   FSSpecPtr fileSpec,
   OSType fileType,
   OSType fileNameExtension,
   Boolean *outCanOpenWithGraphicsImporter,
   Boolean *outCanOpenAsMovie,
   Boolean *outPreferGraphicsImporter,
   UInt32 inFlags
);
Parameters
fileSpec

Points to an FSSpec structure that identifies a file. To ask about a particular file type or file name suffix in general, pass NIL.

fileType

Contains the file type if already known, or 0 if not known. If fileSpec is provided and fileType is 0, QuickTime will determine the file type. If you pass NIL in fileSpec and 0 in fileNameExtension, you must pass a file type here.

fileNameExtension

Contains the file name suffix if already known, or 0 if not known. The file name suffix should be encoded as an uppercase four character code with trailing spaces; for instance, the suffix ".png" should be encoded as 'PNG ', or 0x504E4720. If fileSpec is provided and fileNameExtension is 0, QuickTime will examine fileSpec to determine the file name suffix. If you pass NIL in fileSpec and 0 in fileType, you must pass a file name suffix here.

outCanOpenWithGraphicsImporter

Points to a Boolean that will be set to TRUE if the file can be opened using a graphics importer and FALSE otherwise. If you do not want this information, pass NIL.

outCanOpenAsMovie

Points to a Boolean that will be set to TRUE if the file can be opened as a movie and FALSE otherwise. If you do not want this information, pass NIL.

outPreferGraphicsImporter

Points to a boolean which will be set to true if the file can be opened using a graphics importer and opened as a movie, but, other factors being equal, QuickTime prefers a graphics importer. For example, QuickTime recommends using a graphics importer for single-frame GIF files and opening as a movie for multiple-frame GIF files. If you do not want this information, pass NIL. Passing a valid pointer disables the kQTDontUseDataToFindImporter and kQTDontLookForMovieImporterIfGraphicsImporterFound flags, if set.

inFlags

Flags (see below) that modify search behavior. Pass 0 for default behavior. See these constants:

  • kQTDontUseDataToFindImporter

  • kQTDontLookForMovieImporterIfGraphicsImporterFound

  • kQTAllowOpeningStillImagesAsMovies

  • kQTAllowImportersThatWouldCreateNewFile

  • kQTAllowAggressiveImporters

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function determines whether QuickTime can open a given file or, in general, files of a given type. You should pass NIL in parameters that do not interest you, since that will allow QuickTime to perform a faster determination.

Version Notes

Introduced in QuickTime 5.

Availability
Related Sample Code
Declared In
Movies.h

ClearMovieChanged

Sets the movie changed flag to indicate that the movie has not been changed.

void ClearMovieChanged (
   Movie theMovie
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

CloseMovieFile

Closes an open movie file.

OSErr CloseMovieFile (
   short resRefNum
);
Parameters
resRefNum

The movie file to close. Your application obtains this reference number from OpenMovieFile.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The following code shows a typical use of CloseMovieFile.

// CloseMovieFile coding example
// See "Discovering QuickTime," page 50
void OpenMovie (HWND hwnd, char *szFileName)
{
    short   nFileRefNum =0;
    FSSpec  fss;
    // Convert path to FSSpec
    NativePathNameToFSSpec(szFileName, &fss, 0);
    // Set graphics port
    SetGWorld((CGrafPtr)GetNativeWindowPort(hwnd), NIL);
    OpenMovieFile(&fss, &nFileRefNum, fsRdPerm);   // Open movie file
    NewMovieFromFile(&movie, nFileRefNum, NIL,    // Get movie from file
                        NIL, newMovieActive, NIL);
    CloseMovieFile(nFileRefNum);                   // Close movie file
}
Version Notes

Introduced in QuickTime 3 or earlier. Superseded in QuickTime 6 by CloseMovieStorage.

Availability
Related Sample Code
Declared In
Movies.h

CloseMovieStorage

Closes an open movie storage container.

OSErr CloseMovieStorage (
   DataHandler dh
);
Parameters
dh

The data handler component that was returned by a previous call to CreateMovieStorage.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 6. Supersedes CloseMovieFile.

Availability
Related Sample Code
Declared In
Movies.h

CopyMediaUserData

Copies a source media's user data into a destination media's user data.

OSErr CopyMediaUserData (
   Media srcMedia,
   Media dstMedia,
   OSType copyRule
);
Parameters
srcMedia

The source media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia.

dstMedia

The destination media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia.

copyRule

A constant (see below) that defines how the copying is done. See these constants:

  • kQTCopyUserDataReplace

  • kQTCopyUserDataMerge

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Using this function is equivalent to making the following call:

CopyUserData(GetMediaUserData(srcMedia), GetMediaUserData(dstMedia),
              copyRule);
Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

CopyMovieUserData

Copies a source movie's user data into a destination movie's user data.

OSErr CopyMovieUserData (
   Movie srcMovie,
   Movie dstMovie,
   OSType copyRule
);
Parameters
srcMovie

The source movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

dstMovie

The destination movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

copyRule

A constant (see below) that defines how the copying is done. See these constants:

  • kQTCopyUserDataReplace

  • kQTCopyUserDataMerge

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Using this function is equivalent to making the following call:

CopyUserData(GetMovieUserData(srcMovie), GetMovieUserData(dstMovie),
              copyRule);
Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

CopyTrackUserData

Copies a source track's user data into a destination track's user data.

OSErr CopyTrackUserData (
   Track srcTrack,
   Track dstTrack,
   OSType copyRule
);
Parameters
srcTrack

The source track for this operation. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack.

dstTrack

The destination track for this operation. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack.

copyRule

A constant (see below) that defines how the copying is done. See these constants:

  • kQTCopyUserDataReplace

  • kQTCopyUserDataMerge

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

CopyUserData

Copies metadata items from the source user data container to the destination user data container.

OSErr CopyUserData (
   UserData srcUserData,
   UserData dstUserData,
   OSType copyRule
);
Parameters
srcUserData

The source user data list for this operation. You obtain this list reference by calling GetMovieUserData, GetTrackUserData, or GetMediaUserData.

dstUserData

The destination user data list for this operation. You obtain this list reference by calling GetMovieUserData, GetTrackUserData, or GetMediaUserData.

copyRule

A constant (see below) that defines how the copying is done. See these constants:

  • kQTCopyUserDataReplace

  • kQTCopyUserDataMerge

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The function detects if the source and destination containers already have the same content and does nothing in that case.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

CountUserDataType

Determines the number of items of a given type in a user data list.

short CountUserDataType (
   UserData theUserData,
   OSType udType
);
Parameters
theUserData

The user data list for this operation. You obtain this list reference by calling the GetMovieUserData, GetTrackUserData, or GetMediaUserData functions.

udType

The type. The Movie Toolbox determines the number of items of this type in the user data list.

Return Value

The number of items of the given type in the user data list.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

CreateMovieFile

Creates a movie file, creates an empty movie which references the file, and opens the movie file with write permission.

OSErr CreateMovieFile (
   const FSSpec *fileSpec,
   OSType creator,
   ScriptCode scriptTag,
   long createMovieFileFlags,
   short *resRefNum,
   Movie *newmovie
);
Parameters
fileSpec

A pointer to the file system specification for the movie file to be created.

creator

The creator value for the new file.

scriptTag

The script in which the movie file should be created. Use the Script Manager constant smSystemScript to use the system script; use the smCurrentScript constant to use the current script. See Inside Macintosh: Text for more information about scripts and script tags.

createMovieFileFlags

Controls movie file creation flags (see below). See these constants:

  • createMovieFileDontCreateResFile

  • createMovieFileDeleteCurFile

  • createMovieFileDontCreateMovie

  • createMovieFileDontOpenFile

  • newMovieActive

resRefNum

A pointer to a field that is to receive the file reference number for the opened movie file. Your application must use this value when calling other Movie Toolbox functions that work with movie files. If you set this parameter to NIL, the Movie Toolbox creates the movie file but does not open the file.

newmovie

A pointer to a field that is to receive the identifier of the new movie. CreateMovieFile returns the identifier of the new movie. If the function could not create a new movie, it sets this returned value to NIL. If you set this parameter to NIL, the Movie Toolbox does not create a movie.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The following code snippet shows how CreateMovieFile may be used to create and open a QuickTime movie file.

// CreateMovieFile coding example
// See "Discovering QuickTime," page 243
void CreateMyCoolMovie (void)
{
    StandardFileReply   sfr;
    Movie               movie =NIL;
    FSSpec              fss;
    short               nFileRefNum =0;
    short               nResID =movieInDataForkResID;
    StandardPutFile("\pEnter movie file name:", "\puntitled.mov", &sfr);
    if (!sfr.sfGood)
        return;
    CreateMovieFile(&sfr.sfFile,
                    FOUR_CHAR_CODE('TVOD'),
                    smCurrentScript,
                    createMovieFileDeleteCurFile |
                     createMovieFileDontCreateResFile,
                    &nFileRefNum,
                    &movie);
    CreateMyVideoTrack(movie);   // See "Discovering QuickTime," page 244
    CreateMySoundTrack(movie);   // See "Discovering QuickTime," page 250
    AddMovieResource(movie, nFileRefNum, &nResID, NIL);
    if (nFileRefNum !=0)
        CloseMovieFile(nFileRefNum);
    DisposeMovie(movie);
}
Version Notes

Introduced in QuickTime 3 or earlier. Superseded in QuickTime 6 by CreateMovieStorage.

Availability
Related Sample Code
Declared In
Movies.h

CreateMovieStorage

Creates an empty storage location to hold a movie and opens a data handler to the stored movie with write permission.

OSErr CreateMovieStorage (
   Handle dataRef,
   OSType dataRefType,
   OSType creator,
   ScriptCode scriptTag,
   long createMovieFileFlags,
   DataHandler *outDataHandler,
   Movie *newmovie
);
Parameters
dataRef

A handle to a QuickTime data reference.

dataRefType

The data reference type. See Data References.

creator

The creator type of the new container (for example, 'TV0D', the creator type for Apple's movie player).

scriptTag

Constants (see below) that specify the script for the new container. See these constants:

createMovieFileFlags

Constants (see below) that control file creation options. See these constants:

  • createMovieFileDeleteCurFile

  • createMovieFileDontCreateMovie

  • createMovieFileDontOpenFile

  • newMovieActive

outDataHandler

A pointer to a field that is to receive the data handler for the opened movie container. Your application must use this value when calling other Movie Toolbox functions. If you pass NIL, the Movie Toolbox creates the movie container but does not open it.

newmovie

A pointer to a field that is to receive the returned identifier of the new movie. If the function could not create a new movie, it sets this returned value to NIL. If you pass NIL, the Movie Toolbox does not create a movie.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

If you are writing a custom data handler, make sure it supports DataHGetDataRef. It must also support DataHWrite64, or DataHWrite if 64-bit offsets are not supported.

Version Notes

Introduced in QuickTime 6. Supersedes CreateMovieFile.

Availability
Related Sample Code
Declared In
Movies.h

CreateShortcutMovieFile

Creates a movie file that just contains a reference to another movie.

OSErr CreateShortcutMovieFile (
   const FSSpec *fileSpec,
   OSType creator,
   ScriptCode scriptTag,
   long createMovieFileFlags,
   Handle targetDataRef,
   OSType targetDataRefType
);
Parameters
fileSpec

A pointer to the file system specification for the movie file to be created.

creator

The creator value for the new file.

scriptTag

The script in which the movie file should be created. Use the Script Manager constant smSystemScript to use the system script; use the smCurrentScript constant to use the current script. See Inside Macintosh: Text for more information about scripts and script tags.

createMovieFileFlags

Contains movie file creation flags (see below). See these constants:

  • flattenAddMovieToDataFork

  • flattenDontInterleaveFlatten

  • flattenActiveTracksOnly

  • flattenCompressMovieResource

  • flattenFSSpecPtrIsDataRefRecordPtr

  • flattenForceMovieResourceBeforeMovieData

targetDataRef

A handle to the data referred to by the movie that this function creates.

targetDataRefType

The type of the data referred to by the movie that this function creates; see Data References.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
Movies.h

DeleteMovieFile

Deletes a movie file.

OSErr DeleteMovieFile (
   const FSSpec *fileSpec
);
Parameters
fileSpec

A pointer to the file system specification for the movie file to be deleted.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier. Superseded in QuickTime 6 by DeleteMovieStorage.

Availability
Related Sample Code
Declared In
Movies.h

DeleteMovieStorage

Deletes a movie storage container.

OSErr DeleteMovieStorage (
   Handle dataRef,
   OSType dataRefType
);
Parameters
dataRef

A handle to a QuickTime data reference that identifies the movie storage to be deleted.

dataRefType

The data reference type. See Data References.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

If you are writing a custom data handler that supports this call, make sure that it implements DataHDeleteFile.

Version Notes

Introduced in QuickTime 6. Supersedes DeleteMovieFile.

Availability
Declared In
Movies.h

DetachMovieFromCurrentThread

Detaches a movie from the current thread.

OSErr DetachMovieFromCurrentThread (
   Movie m
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

See Error Codes in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

DisposeActionsUPP

Disposes of an ActionsUPP pointer.

void DisposeActionsUPP (
   ActionsUPP userUPP
);
Parameters
userUPP

An ActionsUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeAllSprites

Disposes of all sprites associated with a sprite world.

void DisposeAllSprites (
   SpriteWorld theSpriteWorld
);
Parameters
theSpriteWorld

The sprite world for this operation.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

This function calls DisposeSprite for each sprite associated with the sprite world.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

DisposeDoMCActionUPP

Disposes of a DoMCActionUPP pointer.

void DisposeDoMCActionUPP (
   DoMCActionUPP userUPP
);
Parameters
userUPP

A DoMCActionUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeGetMovieUPP

Disposes of a GetMovieUPP pointer.

void DisposeGetMovieUPP (
   GetMovieUPP userUPP
);
Parameters
userUPP

A GetMovieUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeMovieController

Disposes of a movie controller.

void DisposeMovieController (
   ComponentInstance mc
);
Parameters
mc

The movie controller for the operation. You obtain this identifier from the Component Manager's OpenComponent or OpenDefaultComponent function, or from the NewMovieController function.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

This function is implemented by the Movie Toolbox, not by movie controller components. If you are creating your own movie controller component, you do not have to support this function. The following code snippet illustrates its use:

// DisposeMovieController coding example
// See "Discovering QuickTime," page 221
// Resource identifiers
#define IDM_OPEN         101
char            szMovieFile[MAX_PATH];              // Name of movie file
Movie           movie;                              // Movie object
MovieController mc;                                 // Movie controller
int WINAPI WinMain (HINSTANCE hInstance, HINSTANCE hPrevInstance,
                      LPSTR lpCmdLine, int nCmdShow)
{
    ...
    ...
    InitializeQTML(0);                          // Initialize QuickTime
    EnterMovies();                              // Initialize Toolbox
    ...
    //  Main message loop
    ...
    ExitMovies();                               // Terminate Toolbox
    TerminateQTML();                            // Terminate QuickTime
}  // end WinMain
//
LRESULT CALLBACK WndProc (HWND hwnd, UINT iMsg, WPARAM wParam, LPARAM lParam)
{
    MSG             msg;
    EventRecord     er;
 
    . . .                                       // Fill in contents of MSG structure
 
    WinEventToMacEvent(&msg, &er);                  // Convert message to a QT event
    MCIsPlayerEvent(mc, (const EventRecord *)&er);  // Pass event to movie controller
 
    switch (iMsg) {
        case WM_CREATE:
            CreatePortAssociation(hwnd, NIL, 0L);  // Register window with QT
            break;
        case WM_COMMAND:
            switch (LOWORD(wParam)) {
                case IDM_OPEN:
                    MyCloseMovie();                 // Close previous movie, if any
 
                    if (MyGetFile(szMovieFile))         // Get file name from user
                        MyOpenMovie(hwnd, szMovieFile); // Open the movie
                    break;
                    . . .
                default:
                    return DefWindowProc(hwnd, iMsg, wParam, lParam);
            }  // end switch (LOWORD(wParam))
            break;
        case WM_CLOSE:
            DestroyPortAssociation(GetNativeWindowPort(hwnd));  // Unregister window
            break;
        . . .
        default:
            return DefWindowProc(hwnd, iMsg, wParam, lParam);
 
    }  // end switch (iMsg)
 
    return 0;
}  // end WndProc
//
BOOL MyGetFile (char *lpszMovieFile)
{
    OPENFILENAME         ofn;
 
    // Fill in contents of OPENFILENAME structure
                ...
                ...
 
     if (GetOpenFileName(&ofn))                     // Let user select file
        return TRUE;
    else
        return FALSE;
}  // end MyGetFile
//
void MyOpenMovie (HWND hwnd, char szFileName[255])
{
    short   nFileRefNum =0;
    FSSpec  fss;
    SetGWorld((CGrafPtr)GetNativeWindowPort(hwnd), NIL);   // Set graphics port
    NativePathNameToFSSpec(szFileName, &fss, 0);    // Convert pathname and make FSSpec
    OpenMovieFile(&fss, &nFileRefNum, fsRdPerm);    // Open movie file
    NewMovieFromFile(&movie, nFileRefNum, NIL,     // Get movie from file
                    NIL, newMovieActive, NIL);
    CloseMovieFile(nFileRefNum);                    // Close movie file
 
    mc =NewMovieController(movie, ...);            // Make movie controller
        ...
        ...
 
}  // end MyOpenMovie
//
void MyCloseMovie (void)
{
    if (mc)                                     // Destroy movie controller, if any
        DisposeMovieController(mc);
 
    if (movie)                                  // Destroy movie object, if any
        DisposeMovie(movie);
}  // end MyCloseMovie
Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

DisposeMovieDrawingCompleteUPP

Disposes of a MovieDrawingCompleteUPP pointer.

void DisposeMovieDrawingCompleteUPP (
   MovieDrawingCompleteUPP userUPP
);
Parameters
userUPP

A MovieDrawingCompleteUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Related Sample Code
Declared In
Movies.h

DisposeMovieExecuteWiredActionsUPP

Disposes of a MovieExecuteWiredActionsUPP pointer.

void DisposeMovieExecuteWiredActionsUPP (
   MovieExecuteWiredActionsUPP userUPP
);
Parameters
userUPP

A MovieExecuteWiredActionsUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeMoviePrePrerollCompleteUPP

Disposes of a MoviePrePrerollCompleteUPP pointer.

void DisposeMoviePrePrerollCompleteUPP (
   MoviePrePrerollCompleteUPP userUPP
);
Parameters
userUPP

A MoviePrePrerollCompleteUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Related Sample Code
Declared In
Movies.h

DisposeMoviePreviewCallOutUPP

Disposes of a MoviePreviewCallOutUPP pointer.

void DisposeMoviePreviewCallOutUPP (
   MoviePreviewCallOutUPP userUPP
);
Parameters
userUPP

A MoviePreviewCallOutUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeMovieProgressUPP

Disposes of a MovieProgressUPP pointer.

void DisposeMovieProgressUPP (
   MovieProgressUPP userUPP
);
Parameters
userUPP

A MovieProgressUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeMovieRgnCoverUPP

Disposes of a MovieRgnCoverUPP pointer.

void DisposeMovieRgnCoverUPP (
   MovieRgnCoverUPP userUPP
);
Parameters
userUPP

A MovieRgnCoverUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeMoviesErrorUPP

Disposes of a MoviesErrorUPP pointer.

void DisposeMoviesErrorUPP (
   MoviesErrorUPP userUPP
);
Parameters
userUPP

A MoviesErrorUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeQTCallBackUPP

Disposes of a QTCallBackUPP pointer.

void DisposeQTCallBackUPP (
   QTCallBackUPP userUPP
);
Parameters
userUPP

A QTCallBackUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeQTEffectListFilterUPP

Disposes of a QTEffectListFilterUPP pointer.

void DisposeQTEffectListFilterUPP (
   QTEffectListFilterUPP userUPP
);
Parameters
userUPP

A QTEffectListFilterUPP pointer. See Universal Procedure Pointers.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

DisposeQTNextTaskNeededSoonerCallbackUPP

Disposes of a QTNextTaskNeededSoonerCallbackUPP pointer.

void DisposeQTNextTaskNeededSoonerCallbackUPP (
   QTNextTaskNeededSoonerCallbackUPP userUPP
);
Parameters
userUPP

A QTNextTaskNeededSoonerCallbackUPP pointer. See Universal Procedure Pointers.

Version Notes

Introduced in QuickTime 6.

Availability
Related Sample Code
Declared In
Movies.h

DisposeQTSyncTaskUPP

Disposes of a QTSyncTaskUPP pointer.

void DisposeQTSyncTaskUPP (
   QTSyncTaskUPP userUPP
);
Parameters
userUPP

A QTSyncTaskUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeSprite

Disposes of a sprite.

void DisposeSprite (
   Sprite theSprite
);
Parameters
theSprite

The sprite to be disposed of.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

You call this function to dispose of a sprite created by NewSprite. The image description handle and image data pointer associated with the sprite are not disposed of by this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

DisposeSpriteWorld

Disposes of a sprite world.

void DisposeSpriteWorld (
   SpriteWorld theSpriteWorld
);
Parameters
theSpriteWorld

The sprite world to dispose of. It is safe to pass NIL to this function.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

You call this function to dispose of a sprite world created by NewSpriteWorld. This function also disposes of all of the sprites associated with the sprite world. This function does not dispose of the graphics worlds associated with the sprite world. Here is an example of using it:

// DisposeSpriteWorld coding example
// See "Discovering QuickTime," page 347
#define kNumSprites             4
#define kNumSpaceShipImages     24
SpriteWorld                 gSpriteWorld =NIL;
Sprite                      gSprites[kNumSprites];
Handle                      gCompressedPictures[kNumSpaceShipImages];
ImageDescriptionHandle      gImageDescriptions[kNumSpaceShipImages];
void MyDisposeEverything (void)
{
    short           nIndex;
    // dispose of the sprite world and associated graphics world
    if (gSpriteWorld)
        DisposeSpriteWorld(gSpriteWorld);
 
    // dispose of each sprite's image data
    for (nIndex =0; nIndex < kNumSprites; nIndex++) {
        if (gCompressedPictures[nIndex])
            DisposeHandle(gCompressedPictures[nIndex]);
        if (gImageDescriptions[nIndex])
            DisposeHandle((Handle)gImageDescriptions[nIndex]);
    }
    DisposeGWorld(spritePlane);
}
Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

DisposeTextMediaUPP

Disposes of a TextMediaUPP pointer.

void DisposeTextMediaUPP (
   TextMediaUPP userUPP
);
Parameters
userUPP

A TextMediaUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeTrackTransferUPP

Disposes of a TrackTransferUPP pointer.

void DisposeTrackTransferUPP (
   TrackTransferUPP userUPP
);
Parameters
userUPP

A TrackTransferUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeTweenerDataUPP

Disposes of a TweenerDataUPP pointer.

void DisposeTweenerDataUPP (
   TweenerDataUPP userUPP
);
Parameters
userUPP

A TweenerDataUPP pointer. See Universal Procedure Pointers.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

DisposeUserData

Disposes of a user data structure created by NewUserData.

OSErr DisposeUserData (
   UserData theUserData
);
Parameters
theUserData

The user data structure that is to be disposed of. It is acceptable but unnecessary to pass NIL in this parameter.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

EndFullScreen

Ends full-screen mode for a graphics device.

OSErr EndFullScreen (
   Ptr fullState,
   long flags
);
Parameters
fullState

The pointer to private state information returned by a previous call to BeginFullScreen.

flags

Reserved. Set this parameter to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function restores the graphics device and other settings to the state specified by the private state information pointed to by the fullState parameter. The resulting state is that that was in effect prior to the immediately previous call to BeginFullScreen. The following code illustrates its use:

OSErr QTFullScreen_RestoreScreen (void)
{
    OSErr       myErr =noErr;
 
#if TARGET_OS_WIN32
    DestroyPortAssociation((CGrafPtr)gFullScreenWindow);
#endif
    DisposeMovieController(gMC);
    myErr =EndFullScreen(gRestoreState, 0L);
 
    return(myErr);
}
Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

FlattenMovie

Creates a new movie file containing a specified movie.

void FlattenMovie (
   Movie theMovie,
   long movieFlattenFlags,
   const FSSpec *theFile,
   OSType creator,
   ScriptCode scriptTag,
   long createMovieFileFlags,
   short *resId,
   ConstStr255Param resName
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

movieFlattenFlags

Contains flags (see below) that control the process of adding movie data to the new movie file. Set unused flags to 0. See these constants:

  • flattenAddMovieToDataFork

  • flattenDontInterleaveFlatten

  • flattenActiveTracksOnly

  • flattenCompressMovieResource

  • flattenFSSpecPtrIsDataRefRecordPtr

  • flattenForceMovieResourceBeforeMovieData

theFile

A pointer to the file system specification for the movie file to be created.

creator

The creator value for the new file.

scriptTag

The script in which the movie file should be created. Set this parameter to the Script Manager constant smSystemScript to use the system script; set it to smCurrentScript to use the current script. See Inside Macintosh: Text for more information about scripts and script tags.

createMovieFileFlags

Contains flags (see below) that control file creation options. See these constants:

  • createMovieFileDeleteCurFile

resId

A pointer to a field that contains the resource ID number for the new resource. If the field referred to by the resId parameter is set to 0, the Movie Toolbox assigns a unique resource ID number to the new resource. The toolbox then returns the movie's resource ID number in the field referred to by the resId parameter. The Movie Toolbox assigns resource ID numbers sequentially, starting at 128. If the resId parameter is set to NIL, the Movie Toolbox assigns a unique resource ID number to the new resource and does not return that resource's ID value.

resName

Points to a character string with the name of the movie resource. If you set the resName parameter to NIL, the toolbox creates an unnamed resource.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

The file created by FlattenMovie also contains all the data for the movie; that is, the Movie Toolbox resolves any data references and includes the corresponding movie data in the new movie file.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

FlattenMovieData

Creates a new movie and a file that contains all the movie data.

Movie FlattenMovieData (
   Movie theMovie,
   long movieFlattenFlags,
   const FSSpec *theFile,
   OSType creator,
   ScriptCode scriptTag,
   long createMovieFileFlags
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

movieFlattenFlags

Contains flags (see below) that control the process of adding movie data to the new movie file. These flags affect how the toolbox adds movies to the new movie file later. Set unused flags to 0. See these constants:

  • flattenAddMovieToDataFork

  • flattenDontInterleaveFlatten

  • flattenActiveTracksOnly

  • flattenCompressMovieResource

  • flattenFSSpecPtrIsDataRefRecordPtr

  • flattenForceMovieResourceBeforeMovieData

theFile

This parameter usually contains a pointer to the file system specification for the movie file to be created. In place of a FSSpec pointer, QuickTime lets you pass a pointer to a data reference structure to receive the flattened movie data.

creator

The creator value for the new file.

scriptTag

Contains constants (see below) that specify the script in which the movie file should be created. See Inside Macintosh: Text for more information about scripts and script tags. See these constants:

createMovieFileFlags

Contains flags (see below) that control file creation options. See these constants:

  • createMovieFileDeleteCurFile

Return Value

The identifier of the new movie. If the function could not create the movie, it sets this returned identifier to NIL.

Discussion

This function will take any movie and optionally make it self-contained, interleaved, and Fast Start. Unlike FlattenMovie, this function does not add the new movie resource to the new movie file; instead, FlattenMovieData returns the new movie to your application. Your application must dispose of the returned movie. You can use this function to create a single-fork movie file, by setting the flattenAddMovieToDataFork flag in the movieFlattenFlags parameter to 1. The Movie Toolbox then places the movie into the data fork of the movie file. Instead of flattening to a file, you can specify a data reference to flatten a movie to. The following two code samples show flattening a movie to a data location and to a file:

// FlattenMovieData used to flatten a movie to a data location
// create a 0-length handle
    myHandle =NewHandleClear(mySize);
    if (myHandle ==NIL)
        goto bail;
 
// fill in the data reference record
    myDataRefRec.dataRefType =HandleDataHandlerSubType;
    myDataRefRec.dataRef =NewHandle(sizeof(Handle));
    if (myDataRefRec.dataRef ==NIL)
        goto bail;
    *((Handle *)*(myDataRefRec.dataRef)) =myHandle;
    myFlags =flattenFSSpecPtrIsDataRefRecordPtr;
    myFile =(FSSpec *)&myDataRefRec;
    // flatten the source movie into the handle
    myMemMovie =FlattenMovieData(mySrcMovie, myFlags, myFile, 0L,
                                  smSystemScript, 0L);
    Movie aMovie;
    aMovie =FlattenMovieData(theMovie,
        flattenAddMovieToDataFork |
        flattenForceMovieResourceBeforeMovieData,
        &theOutputFile, OSTypeConst('TVOD'), smSystemScript,
        createMovieFileDeleteCurFile | createMovieFileDontCreateResFile);
 
    DisposeMovie(aMovie);
    Movie aMovie;
    aMovie =FlattenMovieData(theMovie,
        flattenAddMovieToDataFork,
        &theOutputFile, OSTypeConst('TVOD'), smSystemScript,
        createMovieFileDeleteCurFile | createMovieFileDontCreateResFile);
 
    DisposeMovie(aMovie);
// FlattenMovieData used to flatten a movie to a Fast Start file
// See "Discovering QuickTime," page 257
myErr =OpenMovieFile(&myTempSpec, &myTempResRefNum, fsRdPerm);
if (myErr !=noErr)
    goto bail;
myErr =NewMovieFromFile(&myTempMovie, myTempResRefNum, NIL, 0, 0, 0);
if (myErr !=noErr)
    goto bail;
SetMovieProgressProc(myTempMovie, (MovieProgressUPP)-1, 0L);
// flatten the temporary file into a new movie file; put the movie
// resource first so that progressive downloading is possible
myPanoMovie =FlattenMovieData(
                        myTempMovie,
                        flattenDontInterleaveFlatten
                        | flattenAddMovieToDataFork
                        | flattenForceMovieResourceBeforeMovieData,
                        &myDestSpec,
                        FOUR_CHAR_CODE('TVOD'),
                        smSystemScript,
                        createMovieFileDeleteCurFile
                        | createMovieFileDontCreateResFile);
Special Considerations

Through the SetTrackLoadSettings function, the Movie Toolbox allows you to set a movie's preloading guidelines when you create the movie. The preload information is preserved when you save or flatten the movie (using either FlattenMovie or FlattenMovieData). In flattened movies, the tracks that are to be preloaded are stored at the start of the movie, rather than being interleaved with the rest of the movie data. This greatly improves preload performance because it is not necessary for the device storing the movie data to seek during retrieval of the data to be preloaded.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

FlattenMovieDataToDataRef

Performs a flattening operation to a movie at a storage location.

Movie FlattenMovieDataToDataRef (
   Movie theMovie,
   long movieFlattenFlags,
   Handle dataRef,
   OSType dataRefType,
   OSType creator,
   ScriptCode scriptTag,
   long createMovieFileFlags
);
Parameters
theMovie

The movie passed into this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

movieFlattenFlags

Constants (see below) that control the process of adding movie data to the new container. QuickTime will read these flags later when it adds movies to the storage. Set unused flags to 0. See these constants:

  • flattenAddMovieToDataFork

  • flattenDontInterleaveFlatten

  • flattenActiveTracksOnly

  • flattenCompressMovieResource

  • flattenForceMovieResourceBeforeMovieData

dataRef

A handle to a QuickTime data reference.

dataRefType

The data reference type. See Data References.

creator

The creator type of the new container (for example, 'TV0D', the creator type for Apple's movie player).

scriptTag

Constants (see below) that specify the script for the new container. See these constants:

createMovieFileFlags

Constants (see below) that control file creation options. See these constants:

  • createMovieFileDeleteCurFile

  • createMovieFileDontCreateMovie

  • createMovieFileDontOpenFile

Return Value

The identifier of the new movie. If the function could not create the movie, it sets the returned identifier to NIL.

Discussion

This function performs a flattening operation to the destination data reference.

Version Notes

Introduced in QuickTime 6.

Availability
Related Sample Code
Declared In
Movies.h

GetMaxLoadedTimeInMovie

When a movie is being progressively downloaded, returns the duration of the part of a movie that has already been downloaded.

OSErr GetMaxLoadedTimeInMovie (
   Movie theMovie,
   TimeValue *time
);
Parameters
theMovie

The movie for this operation. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

time

The duration of the part of a movie that has already been downloaded. This time value is expressed in the movie's time coordinate system. If all of a movie has been downloaded, this parameter returns the duration of the entire movie.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The Movie Toolbox creates a time table for a movie when either QTMovieNeedsTimeTable or GetMaxLoadedTimeInMovie is called for the movie, but the time table is used only by the toolbox and is not accessible to applications. The toolbox disposes of the time table when the download is complete.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMediaDataRef

Returns a copy of a specified data reference.

OSErr GetMediaDataRef (
   Media theMedia,
   short index,
   Handle *dataRef,
   OSType *dataRefType,
   long *dataRefAttributes
);
Parameters
theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

index

The index value that corresponds to the data reference. It must be less than or equal to the value that is returned by GetMediaDataRefCount.

dataRef

A pointer to a field that is to receive a handle to the data reference. The media handler returns a handle to information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter. If the function cannot locate the specified data reference, the handler sets this returned value to NIL. Set the dataRef parameter to NIL if you are not interested in this information.

dataRefType

A pointer to a field that is to receive the type of data reference. If the data reference is an alias, the media handler sets this value to 'alis'. Set the dataRefType parameter to NIL if you are not interested in this information.

dataRefAttributes

A pointer to a field that is to receive the reference's attribute flags (see below). Unused flags are set to 0. See these constants:

  • dataRefSelfReference

  • dataRefWasNotResolved

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Use this function to retrieve information about a data reference. For example, you might want to verify the condition of a movie's data references after loading the movie from its movie file. You could use this function to check each data reference.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMediaDataRefCount

Determines the number of data references in a media.

OSErr GetMediaDataRefCount (
   Media theMedia,
   short *count
);
Parameters
theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

count

A pointer to a field that is to receive the number of data references in the media.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMediaNextInterestingDecodeTime

Searches for decode times of interest in a media.

void GetMediaNextInterestingDecodeTime (
   Media theMedia,
   short interestingTimeFlags,
   TimeValue64 decodeTime,
   Fixed rate,
   TimeValue64 *interestingDecodeTime,
   TimeValue64 *interestingDecodeDuration
);
Parameters
theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

interestingTimeFlags

Flags that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, or nextTimeSyncSample flags to 1. Set unused flags to 0: nextTimeMediaSample Set this flag to 1 to search for the next sample. nextTimeMediaEdit Set this flag to 1 to search for the next group of samples. nextTimeSyncSample Set this flag to 1 to search for the next sync sample. nextTimeEdgeOK Set this flag to 1 to accept information about elements that begin or end at the time specified by the decodeTime parameter. When this flag is set the function returns valid information about the beginning and end of a media. See these constants:

  • nextTimeMediaSample

  • nextTimeMediaEdit

  • nextTimeSyncSample

  • nextTimeEdgeOK

decodeTime

Specifies the starting point for the search in decode time. This time value must be expressed in the media's time scale.

rate

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.

interestingDecodeTime

On return, a pointer to a 64-bit time value in decode time. 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 media's time scale. If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1. Set this parameter to NULL if you are not interested in this information.

interestingDecodeDuration

On return, a pointer to a 64-bit time value in decode time. The Movie Toolbox returns the duration of the interesting time in the media's time coordinate system. Set this parameter to NULL if you don't want this information; this lets the function works faster.

Availability
Declared In
Movies.h

GetMediaNextInterestingDisplayTime

Searches for display times of interest in a media.

void GetMediaNextInterestingDisplayTime (
   Media theMedia,
   short interestingTimeFlags,
   TimeValue64 displayTime,
   Fixed rate,
   TimeValue64 *interestingDisplayTime,
   TimeValue64 *interestingDisplayDuration
);
Parameters
theMedia

The media for this operation. You obtain this media identifier from such functions as NewTrackMedia and GetTrackMedia.

interestingTimeFlags

Flags that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, or nextTimeSyncSample flags to 1. Set unused flags to 0: nextTimeMediaSample Set this flag to 1 to search for the next sample. nextTimeMediaEdit Set this flag to 1 to search for the next group of samples. nextTimeSyncSample Set this flag to 1 to search for the next sync sample. nextTimeEdgeOK Set this flag to 1 to accept information about elements that begin or end at the time specified by the decodeTime parameter. When this flag is set the function returns valid information about the beginning and end of a media. See these constants:

  • nextTimeMediaSample

  • nextTimeMediaEdit

  • nextTimeSyncSample

  • nextTimeEdgeOK

displayTime

Specifies the starting point for the search in display time. This time value must be expressed in the media's time scale.

rate

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.

interestingDisplayTime

On return, a pointer to a 64-bit time value in display time. 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 media's time scale. If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1. Set this parameter to NIL if you are not interested in this information.

interestingDisplayDuration

On return, a pointer to a 64-bit time value in display time. The Movie Toolbox returns the duration of the interesting time in the media's time coordinate system. Set this parameter to NIL if you don't want this information; this lets the function works faster.

Availability
Declared In
Movies.h

GetMediaNextInterestingTime

Searches for times of interest in a media.

void GetMediaNextInterestingTime (
   Media theMedia,
   short interestingTimeFlags,
   TimeValue time,
   Fixed rate,
   TimeValue *interestingTime,
   TimeValue *interestingDuration
);
Parameters
theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

interestingTimeFlags

Contains flags (see below) that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit or nextTimeSyncSample flags to 1. Set unused flags to 0. See these constants:

  • nextTimeMediaSample

  • nextTimeMediaEdit

  • nextTimeSyncSample

  • nextTimeEdgeOK

time

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

rate

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

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 media's time scale. If there are no times that meet the search criteria you specify, the Movie Toolbox sets this value to -1. Set this parameter to NIL if you are not interested in this information.

interestingDuration

A pointer to a time value. The Movie Toolbox returns the duration of the interesting time. This time value is in the media's time coordinate system. Set this parameter to NIL if you don't want this information; this lets the function works faster.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Discussion

Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample. They do this by deriving frames from sync samples, which don't rely on preceding frames for content.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetMediaPlayHints

Undocumented

void GetMediaPlayHints (
   Media theMedia,
   long *flags
);
Parameters
theMedia

The media for this operation. Your application obtains this media identifier from such functions as NewTrackMedia and GetTrackMedia. See Media Identifiers.

flags

Undocumented

Return Value

Undocumented

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMediaPropertyAtom

Retrieves the property atom container of a media handler.

OSErr GetMediaPropertyAtom (
   Media theMedia,
   QTAtomContainer *propertyAtom
);
Parameters
theMedia

A reference to the media handler for this operation.

propertyAtom

A pointer to a QT atom container. On return, the atom container contains the property atoms for the track associated with the media handler.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

You can call GetMediaPropertyAtom to retrieve the properties of the track associated with the specified media handler. The contents of the returned QT atom container are defined by the media handler.

Special Considerations

The caller is responsible for disposing of the QT atom container.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetMovieAnchorDataRef

Retrieves a movie's anchor data reference and type.

OSErr GetMovieAnchorDataRef (
   Movie theMovie,
   Handle *dataRef,
   OSType *dataRefType,
   long *outFlags
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

dataRef

A handle to the data reference. The type of information stored in the handle depends upon the data reference type specified by dataRefType.

dataRefType

The type of data reference; see Data References.

outFlags

If there is no anchor data reference associated with the movie, then GetMovieAnchorDataRef sets this parameter to kMovieAnchorDataRefIsDefault (see below) and returns copies of the default data reference and type. See these constants:

  • kMovieAnchorDataRefIsDefault

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

If there is neither an anchor nor a default data reference, NIL will be returned in dataRef and 0 in dataRefType.

Special Considerations

The caller should dispose of the data reference returned.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

GetMovieAudioBalance

Returns the balance value for the audio mix of a movie currently playing.

OSStatus GetMovieAudioBalance (
   Movie m,
   Float32 *leftRight,
   UInt32 flags
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

leftRight

On return, a pointer to the current balance setting for the movie. The balance setting is a 32-bit floating-point value that controls the relative volume of the left and right sound channels. A value of 0 sets the balance to neutral. Positive values up to 1.0 shift the balance to the right channel, negative values up to -1.0 to the left channel.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The movie's balance setting is not stored in the movie; it is used only until the movie is closed. See SetMovieAudioBalance.

Availability
Declared In
Movies.h

GetMovieAudioFrequencyLevels

Returns the current frequency meter levels of a movie mix.

OSStatus GetMovieAudioFrequencyLevels (
   Movie m,
   FourCharCode whatMixToMeter,
   QTAudioFrequencyLevels *pAveragePowerLevels
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see Movie Audio Mixes.

pAveragePowerLevels

A pointer to a QTAudioFrequencyLevels structure (page 325).

Return Value

An error code. Returns noErr if there is no error.

Discussion

In the structure pointed to by pAveragePowerLevels, the numChannels field must be set to the number of channels in the movie mix being metered and the numBands field must be set to the number of bands being metered (as previously configured). Enough memory for the structure must be allocated to hold 32-bit values for all bands in all channels. This function returns the current frequency meter levels in the level field of the structure, with all the band levels for the first channel first, all the band levels for the second channel next and so on.

Availability
Declared In
Movies.h

GetMovieAudioFrequencyMeteringBandFrequencies

Returns the chosen middle frequency for each band in the configured frequency metering of a particular movie mix.

OSStatus GetMovieAudioFrequencyMeteringBandFrequencies (
   Movie m,
   FourCharCode whatMixToMeter,
   UInt32 numBands,
   Float32 *outBandFrequencies
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see Movie Audio Mixes.

numBands

The number of bands to examine.

outBandFrequencies

A pointer to an array of frequencies, each expressed in Hz.

Return Value

An error code. Returns noErr if there is no error.

Discussion

You can use this function to label a visual meter in a user interface.

Availability
Declared In
Movies.h

GetMovieAudioFrequencyMeteringNumBands

Returns the number of frequency bands being metered for a movie's specified audio mix.

OSStatus GetMovieAudioFrequencyMeteringNumBands (
   Movie m,
   FourCharCode whatMixToMeter,
   UInt32 *outNumBands
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see Movie Audio Mixes.

outNumBands

A pointer to memory that stores the number of frequency bands currently being metered for the movie's specified audio mix.

Return Value

An error code. Returns noErr if there is no error.

Discussion

See SetMovieAudioFrequencyMeteringNumBands.

Availability
Declared In
Movies.h

GetMovieAudioGain

Returns the gain value for the audio mix of a movie currently playing.

OSStatus GetMovieAudioGain (
   Movie m,
   Float32 *gain,
   UInt32 flags
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

gain

A 32-bit floating-point gain value of 0 or greater. This value is multiplied by the movie's volume. 0.0 is silent, 0.5 is -6 dB, 1.0 is 0 dB (the audio from the movie is not modified), 2.0 is +6 dB, etc. The gain level can be set higher than 1.0 to allow quiet movies to be boosted in volume. Gain settings higher than 1.0 may result in audio clipping.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The movie gain setting is not stored in the movie; it is used only until the movie is closed. See SetMovieAudioGain.

Availability
Declared In
Movies.h

GetMovieAudioMute

Returns the mute value for the audio mix of a movie currently playing.

OSStatus GetMovieAudioMute (
   Movie m,
   Boolean *muted,
   UInt32 flags
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

muted

Returns TRUE if the movie audio is currently muted, FALSE otherwise.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The movie mute setting is not stored in the movie; it is used only until the movie is closed. See SetMovieAudioMute.

Availability
Declared In
Movies.h

GetMovieAudioVolumeLevels

Returns the current volume meter levels of a movie.

OSStatus GetMovieAudioVolumeLevels (
   Movie m,
   FourCharCode whatMixToMeter,
   QTAudioVolumeLevels *pAveragePowerLevels,
   QTAudioVolumeLevels *pPeakHoldLevels
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see Movie Audio Mixes.

pAveragePowerLevels

A pointer to a QTAudioVolumeLevels structure that stores the average power level of each channel in the mix, measured in decibels. A return of NIL means no channels; if non-NIL, 0.0 dB for each channel means full volume, -6.0 dB means half volume, -12.0 dB means quarter volume, and -infinite dB means silence.

pPeakHoldLevels

A pointer to a QTAudioVolumeLevels structure that stores the peak hold level of each channel in the mix, measured in decibels. A return of NIL means no channels; if non-NIL, 0.0 dB for each channel means full volume, -6.0 dB means half volume, -12.0 dB means quarter volume, and -infinite dB means silence.

Return Value

An error code. Returns noErr if there is no error.

Discussion

If either pAveragePowerLevels or pPeakHoldLevels returns non-NIL, it must have the numChannels field in its QTAudioVolumeLevels structure set to the number of channels in the movie mix being metered and the memory allocated for the structure must be large enough to hold levels for all those channels.

Availability
Declared In
Movies.h

GetMovieAudioVolumeMeteringEnabled

Returns the enabled or disabled status of volume metering of a particular audio mix of a movie.

OSStatus GetMovieAudioVolumeMeteringEnabled (
   Movie m,
   FourCharCode whatMixToMeter,
   Boolean *enabled
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

whatMixToMeter

The applicable mix of audio channels in the movie; see Movie Audio Mixes.

enabled

Returns TRUE if audio volume metering is enabled, FALSE if it is disabled.

Return Value

An error code. Returns noErr if there is no error.

Discussion

See SetMovieAudioVolumeMeteringEnabled.

Availability
Declared In
Movies.h

GetMovieColorTable

Retrieves a movie's color table.

OSErr GetMovieColorTable (
   Movie theMovie,
   CTabHandle *ctab
);
Parameters
theMovie

The movie for this operation. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

ctab

A pointer to a field that is to receive a handle to the movie's color table. If the movie does not have a color table, the toolbox sets the field to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The toolbox returns a copy of the color table, so it is your responsibility to dispose of the color table when you are done with it.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMovieCoverProcs

Retrieves the cover functions that you set with the SetMovieCoverProcs function.

OSErr GetMovieCoverProcs (
   Movie theMovie,
   MovieRgnCoverUPP *uncoverProc,
   MovieRgnCoverUPP *coverProc,
   long *refcon
);
Parameters
theMovie

The movie for this operation. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

uncoverProc

Where to return the current uncover procedure. This value is set to NIL if no uncover procedure was specified.

coverProc

Where to return the current cover procedure. This value is set to NIL if no cover procedure was specified.

refcon

A reference constant to be passed to your callback. Use this parameter to point to a data structure containing any information your cover functions need.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function returns the uncover and cover functions for the movie as well as the reference constant for the cover functions.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMovieDefaultDataRef

Gets a movie's default data reference.

OSErr GetMovieDefaultDataRef (
   Movie theMovie,
   Handle *dataRef,
   OSType *dataRefType
);
Parameters
theMovie

A movie identifier. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

dataRef

A pointer to a field that is to receive a handle to the data reference. The function returns a handle to information that identifies the file that contains this media's data. The type of information stored in that handle depends upon the value of the dataRefType parameter. If the function cannot locate the specified data reference, the handler sets this returned value to NIL. Set the dataRef parameter to NIL if you are not interested in this information.

dataRefType

A pointer to a field that is to receive the type of data reference; see Data References. If the data reference is an alias, the function sets this value to 'alis', indicating that the reference is an alias. Set the dataRefType parameter to NIL if you are not interested in this information.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMovieLoadState

Returns a value that indicates the state of a movie's loading process.

long GetMovieLoadState (
   Movie theMovie
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

A constant (see below) that indicates the movie's loading status.

Discussion

This function lets your code perform relative comparisons against movie loading milestones to determine if certain operations make sense. Its return values are ordered so that they conform to this rule:

kMovieLoadStateError
< kMovieLoadStateLoading
< kMovieLoadStatePlayable
< kMovieLoadStateComplete
Special Considerations

Because of the "voting system" involved, an application checking for the load state should throttle its calling of the routine. Not calling GetMovieLoadState more often than every quarter of a second is a good place to start.

Version Notes

Introduced in QuickTime 4.1.

Availability
Related Sample Code
Declared In
Movies.h

GetMovieNextInterestingTime

Searches for times of interest in a movie's enabled tracks.

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

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

interestingTimeFlags

Contains flags (see below) that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, nextTimeTrackEdit and nextTimeSyncSample flags to 1. Set unused flags to 0. See these constants:

  • nextTimeMediaSample

  • nextTimeMediaEdit

  • nextTimeTrackEdit

  • nextTimeSyncSample

  • nextTimeStep

  • nextTimeEdgeOK

  • nextTimeIgnoreActiveSegment

numMediaTypes

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

A pointer to an array of media type constants (see below). 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. See these constants:

  • VisualMediaCharacteristic

  • AudioMediaCharacteristic

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

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

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

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 don't want this information; in this case, the function works faster.

Discussion

The following code sample shows the use of GetMovieNextInterestingTime to return, through the time parameter, the starting time of the first video sample of the specified QuickTime movie. The trick here is to set the nextTimeEdgeOK flag, to indicate that you want to get the starting time of the beginning of the movie. If this function encounters an error, it returns a (bogus) starting time of -1, as shown below:

static OSErr QTStep_GetStartTimeOfFirstVideoSample (Movie theMovie,
                                                    TimeValue *theTime)
{
    short           myFlags;
    OSType          myTypes[1];
 
    *theTime =kBogusStartingTime;               // a bogus starting time
    if (theMovie ==NIL)
        return(invalidMovie);
 
    myFlags =nextTimeMediaSample + nextTimeEdgeOK;
                                 // we want the first sample in the movie
    myTypes[0] =VisualMediaCharacteristic;      // we want video samples
    GetMovieNextInterestingTime(theMovie, myFlags, 1, myTypes,
                                      (TimeValue)0, fixed1, theTime, NIL);
    return(GetMoviesError());
}
Special Considerations

This function examines only the movie's enabled tracks.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetMovieProgressProc

Gets the MovieProgressProc callback attached to a movie.

void GetMovieProgressProc (
   Movie theMovie,
   MovieProgressUPP *p,
   long *refcon
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

p

On return, a pointer to a MovieProgressProc callback.

refcon

On return, a reference constant passed to the callback. This parameter is used to point to a data structure containing any information the function needs.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
Movies.h

GetMoviePropertyAtom

Gets a movie's property atom.

OSErr GetMoviePropertyAtom (
   Movie theMovie,
   QTAtomContainer *propertyAtom
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

propertyAtom

A pointer to a property atom.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This routine is used to author event handlers for the kQTEventMovieLoaded QuickTime event.

Version Notes

Introduced in QuickTime 4.1.

Availability
Declared In
Movies.h

GetMovieSegmentDisplayBoundsRgn

Determines a movie's display boundary region for a specified segment.

RgnHandle GetMovieSegmentDisplayBoundsRgn (
   Movie theMovie,
   TimeValue time,
   TimeValue duration
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

time

The starting time of the movie segment to consider. This time value must be expressed in the movie's time coordinate system. The duration parameter specifies the length of the segment.

duration

The length of the segment to consider. Set this parameter to 0 to specify an instant in time.

Return Value

A handle to a MacRegion structure that the function allocates. This region is defined in the movie's display coordinate system. If the movie does not have a spatial representation at the current time, the function returns an empty region. If the function could not satisfy the request, it sets the returned handle to NIL.

Discussion

This function allocates a region and returns a handle to it. The Movie Toolbox derives the display boundary region only from enabled tracks and only from those tracks that are used in the current display mode (movie, poster, or preview). The display boundary region encloses all of a movie's enabled tracks after the track matrix, track clip, movie matrix, and movie clip have been applied to them.

Special Considerations

Your application must dispose of the returned region when it is done with it.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMovieStatus

Searches for errors in all the enabled tracks of the movie and returns information about errors that are encountered during the processing associated with the MoviesTask function.

ComponentResult GetMovieStatus (
   Movie theMovie,
   Track *firstProblemTrack
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

firstProblemTrack

A pointer to a track identifier. The Movie Toolbox places the identifier for the first track that is found to contain an error into the field referred to by this parameter. If you don't want to receive the track identifier, set this parameter to NIL.

Return Value

See Error Codes. Returns noErr if there is no error in the movie status value.

Discussion

This function returns information about errors that are encountered during MoviesTask execution. These errors typically reflect playback problems, such as low-memory conditions. GetMovieStatus returns the error associated with the first problem track.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetMovieThreadAttachState

Determines whether a given movie is attached to a thread.

OSErr GetMovieThreadAttachState (
   Movie m,
   Boolean *outAttachedToCurrentThread,
   Boolean *outAttachedToAnyThread
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

outAttachedToCurrentThread

A pointer to a Boolean that on exit is TRUE if the movie is attached to the current thread, FALSE otherwise.

outAttachedToAnyThread

A pointer to a Boolean that on exit is TRUE if the movie is attached to any thread, FALSE otherwise.

Return Value

See Error Codes in the QuickTime API Reference. Returns noErr if there is no error.

Version Notes

Introduced in QuickTime 6.4.

Availability
Declared In
Movies.h

GetMovieVisualBrightness

Returns the brightness adjustment for the movie.

OSStatus GetMovieVisualBrightness (
   Movie movie,
   Float32 *brightnessOut,
   UInt32 flags
);
Parameters
movie

The movie.

brightnessOut

Current brightness adjustment.

flags

Reserved. Pass 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The brightness adjustment for the movie. The value is a Float32 for which -1.0 means full black, 0.0 means no adjustment, and 1.0 means full white. The setting is not stored in the movie. It is only used until the movie is closed, at which time it is not saved.

Availability
Declared In
Movies.h

GetMovieVisualContrast

Returns the contrast adjustment for the movie.

OSStatus GetMovieVisualContrast (
   Movie movie,
   Float32 *contrastOut,
   UInt32 flags
);
Parameters
movie

The movie.

contrastOut

Current contrast adjustment.

flags

Reserved. Pass 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The contrast adjustment for the movie. The value is a Float32 percentage (1.0f = 100%), such that 0.0 gives solid gray.

Availability
Declared In
Movies.h

GetMovieVisualHue

Returns the hue adjustment for the movie.

OSStatus GetMovieVisualHue (
   Movie movie,
   Float32 *hueOut,
   UInt32 flags
);
Parameters
movie

The movie.

hueOut

Current hue adjustment. (Float32)

flags

Reserved. Pass 0. (UInt32)

Return Value

An error code. Returns noErr if there is no error.

Discussion

The hue adjustment for the movie. The value is a Float32 between -1.0 and 1.0, with 0.0 meaning no adjustment. This adjustment wraps around, such that -1.0 and 1.0 yield the same result. The setting is not stored in the movie. It is only used until the movie is closed, at which time it is not saved.

Availability
Declared In
Movies.h

GetMovieVisualSaturation

Returns the color saturation adjustment for the movie.

OSStatus GetMovieVisualSaturation (
   Movie movie,
   Float32 *saturationOut,
   UInt32 flags
);
Parameters
movie

The movie.

saturationOut

Current saturation adjustment.(Float32)

flags

Reserved. Pass 0. (UInt32)

Return Value

An error code. Returns noErr if there is no error.

Discussion

The color saturation adjustment for the movie. The value is a Float32 percentage (1.0f = 100%), such that 0.0 gives grayscale. The setting is not stored in the movie. It is only used until the movie is closed, at which time it is not saved.

Availability
Declared In
Movies.h

GetNextUserDataType

Retrieves the next user data type in a specified user data list.

long GetNextUserDataType (
   UserData theUserData,
   OSType udType
);
Parameters
theUserData

The user data list for this operation. You obtain this list reference by calling GetMovieUserData, GetTrackUserData, or GetMediaUserData.

udType

Specifies a user data field; see User Data Identifiers. Set this parameter to 0 to retrieve the first user data field in the user data list. On subsequent requests, use the previous value returned by this function.

Return Value

The next user data type in the list. Returns 0 when there are no more user data types.

Discussion

Use this function to scan all the user data types in a user data list.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetPosterBox

Obtains a poster's boundary rectangle.

void GetPosterBox (
   Movie theMovie,
   Rect *boxRect
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

boxRect

A pointer to a rectangle. The Movie Toolbox returns the poster's boundary rectangle into the structure referred to by this parameter.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetQuickTimePreference

Retrieves a particular preference from the QuickTime preferences.

OSErr GetQuickTimePreference (
   OSType preferenceType,
   QTAtomContainer *preferenceAtom
);
Parameters
preferenceType

A preference type to be retrieved (see below); see Atom ID Codes. See these constants:

  • ConnectionSpeedPrefsType

  • BandwidthManagementPrefsType

preferenceAtom

A pointer to the returned preference atom.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The following sample code shows how to retrieve the connection speed setting from the QuickTime preferences:

struct ConnectionSpeedPrefsRecord {
   long connectionSpeed;
};
typedef struct ConnectionSpeedPrefsRecord ConnectionSpeedPrefsRecord;
. . .
OSErr                       err;
QTAtomContainer             prefs;
QTAtom                      prefsAtom;
long                        dataSize;
Ptr                         atomData;
ConnectionSpeedPrefsRecord  prefrec;
err =GetQuickTimePreference(ConnectionSpeedPrefsType, &amp;prefs);
if (err ==noErr) {
    prefsAtom =QTFindChildByID(prefs, kParentAtomIsContainer,
                                  ConnectionSpeedPrefsType, 1, nil);
    if (!prefsAtom) {
        // set the default setting to 28.8kpbs
        prefrec.connectionSpeed =kDataRate288ModemRate;
    } else {
        err =QTGetAtomDataPtr(prefs, prefsAtom, &dataSize,
                                                         &atomData);
        if (dataSize !=sizeof(ConnectionSpeedPrefsRecord)) {
            // the prefs record wasn't the right size,
            // so it must be corrupt -- set to the default
            prefrec.connectionSpeed =kDataRate288ModemRate;
        } else {
            // everything was fine -- read the connection speed
            prefrec =*(ConnectionSpeedPrefsRecord *)atomData;
        }
    }
    QTDisposeAtomContainer(prefs);
}
Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetSoundDescriptionExtension

Gets the current extension to a SoundDescription structure.

OSErr GetSoundDescriptionExtension (
   SoundDescriptionHandle desc,
   Handle *extension,
   OSType idType
);
Parameters
desc

A handle to a SoundDescription structure.

extension

A pointer to a handle that, on return, contains the extension.

idType

A four-byte signature that identifies the type of data in the extension.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetSpriteProperty

Retrieves the value of a specified sprite property.

OSErr GetSpriteProperty (
   Sprite theSprite,
   long propertyType,
   void *propertyValue
);
Parameters
theSprite

The sprite for this operation.

propertyType

The property whose value should be retrieved (see below). See these constants:

  • kSpritePropertyMatrix

  • kSpritePropertyImageDescription

  • kSpritePropertyImageDataPtr

  • kSpritePropertyVisible

  • kSpritePropertyLayer

  • kSpritePropertyGraphicsMode

  • kSpritePropertyCanBeHitTested

propertyValue

A pointer to a variable that will hold the selected property value on return. Depending on the property type, this parameter is either a pointer to the property value or the property value itself, cast as a void pointer.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

You call this function to retrieve the value of a sprite property, setting the propertyType parameter to the type of the property you want to retrieve.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetTrackAudioGain

Returns the gain value for the audio mix of a track currently playing.

OSStatus GetTrackAudioGain (
   Track t,
   Float32 *gain,
   UInt32 flags
);
Parameters
t

A track identifier, which your application obtains from such functions as NewMovieTrack and GetMovieTrack.

gain

A 32-bit floating-point gain value of 0 or greater. This value is multiplied by the track's volume. 0.0 is silent, 0.5 is -6 dB, 1.0 is 0 dB (the audio from the track is not modified), 2.0 is +6 dB, etc. The gain level can be set higher than 1.0 to allow quiet tracks to be boosted in volume. Gain settings higher than 1.0 may result in audio clipping.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The track gain setting is not stored in the movie; it is used only until the movie is closed. See SetTrackAudioGain.

Availability
Declared In
Movies.h

GetTrackAudioMute

Returns the mute value for the audio mix of a track currently playing.

OSStatus GetTrackAudioMute (
   Track t,
   Boolean *muted,
   UInt32 flags
);
Parameters
t

A track identifier, which your application obtains from such functions as NewMovieTrack and GetMovieTrack.

muted

Returns TRUE if the track's audio is currently muted, FALSE otherwise.

flags

Not used; set to 0.

Return Value

An error code. Returns noErr if there is no error.

Discussion

The track's mute setting is not stored in the movie; it is used only until the movie is closed. See SetTrackAudioMute.

Availability
Declared In
Movies.h

GetTrackLoadSettings

Retrieves a track's preload information.

void GetTrackLoadSettings (
   Track theTrack,
   TimeValue *preloadTime,
   TimeValue *preloadDuration,
   long *preloadFlags,
   long *defaultHints
);
Parameters
theTrack

The track for this operation. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack.

preloadTime

Specifies a field to receive the starting point of the portion of the track to be preloaded. The toolbox returns a value of -1 if the entire track is to be preloaded.

preloadDuration

Specifies a field to receive the amount of the track to be preloaded, starting from the time specified in the preloadTime parameter. If the entire track is to be preloaded, this value is ignored.

preloadFlags

Specifies a field to receive the flags (see below) that control when the toolbox preloads the track. See these constants:

  • preloadAlways

  • preloadOnlyIfEnabled

defaultHints

Specifies a field to receive the playback hints for the track.

Return Value

You can access this function's error returns through GetMoviesError and GetMoviesStickyError.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetTrackNextInterestingTime

Searches for times of interest in a track.

void GetTrackNextInterestingTime (
   Track theTrack,
   short interestingTimeFlags,
   TimeValue time,
   Fixed rate,
   TimeValue *interestingTime,
   TimeValue *interestingDuration
);
Parameters
theTrack

The track for this operation. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack.

interestingTimeFlags

Contains flags (see below) that determine the search criteria. Note that you may set only one of the nextTimeMediaSample, nextTimeMediaEdit, nextTimeTrackEdit and nextTimeSyncSample flags to 1. Set unused flags to 0. See these constants:

  • nextTimeMediaSample

  • nextTimeMediaEdit

  • nextTimeTrackEdit

  • nextTimeSyncSample

  • nextTimeEdgeOK

  • nextTimeIgnoreActiveSegment

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

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

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. Set this parameter to NIL if you are not interested in this information.

interestingDuration

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 don't want this information; in this case, the function works more quickly.

Discussion

Some compression algorithms conserve space by eliminating duplication between consecutive frames in a sample. In this case, sync samples don't rely on preceding frames for content. You can access error returns from this function through GetMoviesError and GetMoviesStickyError. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetTrackSegmentDisplayBoundsRgn

Determines the region a track occupies in a movie's graphics world during a specified segment.

RgnHandle GetTrackSegmentDisplayBoundsRgn (
   Track theTrack,
   TimeValue time,
   TimeValue duration
);
Parameters
theTrack

The track for this operation. Your application obtains this track identifier from such functions as NewMovieTrack and GetMovieTrack.

time

The starting time of the track segment to consider. This time value must be expressed in the movie's time coordinate system. The duration parameter specifies the length of the segment.

duration

The length of the segment to consider. Set this parameter to 0 to consider an instant in time.

Return Value

A handle to the region the specified track occupies in its movie's graphics world during a specified segment. If the track does not have a spatial representation during the specified segment, the function returns an empty region. If the function could not satisfy your request, it sets the returned handle to NIL.

Discussion

This function allocates the region and returns a handle to it. This region is valid for the specified segment.

Special Considerations

Your application must dispose of the returned region when you are done with it.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetTrackStatus

Returns the value of the last error the media encountered while playing a specified track.

ComponentResult GetTrackStatus (
   Track theTrack
);
Parameters
theTrack

The track for this operation. Your application obtains this track identifier from GetMovieStatus.

Return Value

GetTrackStatus returns the last error encountered for the specified track; see Error Codes. If the component does not find any errors, the result is set to noErr.

Discussion

This function returns information about errors that are encountered during the processing associated with MoviesTask. These errors typically reflect playback problems, such as low-memory conditions. This function returns the last error encountered for the specified track. The media clears this error code when it detects that the error has been corrected.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

GetUserData

Returns a specified user data item.

OSErr GetUserData (
   UserData theUserData,
   Handle data,
   OSType udType,
   long index
);
Parameters
theUserData

The user data list for this operation. You obtain this list reference by calling the GetMovieUserData, GetTrackUserData, or GetMediaUserData function.

data

A handle that is to receive the data from the specified item. GetUserData resizes this handle as appropriate to accommodate the item. Your application is responsible for releasing this handle when you are done with it. Set this parameter to NIL if you don't want to retrieve the user data item. This can be useful if you want to verify that a user data item exists, but you don't need to work with the item's contents.

udType

The item's type value; see User Data Identifiers.

index

The item's index value. This parameter must specify an item in the user data list identified by the parameter theUserData.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetUserDataItem

Returns a specified user data item.

OSErr GetUserDataItem (
   UserData theUserData,
   void *data,
   long size,
   OSType udType,
   long index
);
Parameters
theUserData

The user data list for this operation. You obtain this list reference by calling the GetMovieUserData, GetTrackUserData, or GetMediaUserData.

data

A pointer that is to receive the data from the specified item.

size

The size of the item.

udType

The item's type value; see User Data Identifiers.

index

The item's index value. This parameter must specify an item in the user data list identified by the parameter theUserData.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

GetUserDataText

Retrieves language-tagged text from an item in a user data list.

OSErr GetUserDataText (
   UserData theUserData,
   Handle data,
   OSType udType,
   long index,
   short itlRegionTag
);
Parameters
theUserData

The user data list for this operation. You obtain this list reference by calling the GetMovieUserData, GetTrackUserData, or GetMediaUserData function.

data

A handle that is to receive the data. The GetUserDataText function resizes this handle as appropriate. Your application must dispose of the handle when you are done with it.

udType

The item's type value; see User Data Identifiers.

index

The item's index value. This parameter must specify an item in the user data list identified by the parameter theUserData.

itlRegionTag

The language code of the text to be retrieved. See Localization Codes.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

You specify the user data list and item, and the item's type value and language code. The Movie Toolbox retrieves the specified text from the user data item.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

HasMovieChanged

Determines whether a movie has changed and needs to be saved.

Boolean HasMovieChanged (
   Movie theMovie
);
Parameters
theMovie

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

Return Value

Returns TRUE if the movie has changed, FALSE otherwise.

Discussion

Your application can clear the movie changed flag, indicating that the movie has not changed, by calling ClearMovieChanged.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

InvalidateSprite

Invalidates the portion of a sprite's sprite world that is occupied by a sprite.

void InvalidateSprite (
   Sprite theSprite
);
Parameters
theSprite

The sprite for this operation.

Return Value

You can access error returns from this function through GetMoviesError and GetMoviesStickyError. See Error Codes.

Discussion

In most cases, you do not need to call this function. When you call SetSpriteProperty to modify a sprite's properties, it takes care of invalidating the appropriate regions of the sprite world. However, you might call this function if you change a sprite's image data but retain the same image data pointer.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

InvalidateSpriteWorld

Invalidates a rectangular area of a sprite world.

OSErr InvalidateSpriteWorld (
   SpriteWorld theSpriteWorld,
   Rect *invalidArea
);
Parameters
theSpriteWorld

The sprite world for this operation.

invalidArea

A pointer to the Rect structure that defines the area that should be invalidated. This rectangle should be specified in the sprite world's source space, which is the coordinate system of the sprite layer's graphics world before the sprite world's matrix is applied to it. To invalidate the entire sprite world, pass NIL for this parameter.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Typically, your application calls this function when the sprite world's destination window receives an update event. Invalidating an area of the sprite world will cause the area to be redrawn the next time that SpriteWorldIdle is called.

Special Considerations

When you modify sprite properties, invalidation takes place automatically; you do not need to call this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

MakeMediaTimeTable

Returns a time table for the specified media.

ComponentResult ADD_MEDIA_BASENAME() MakeMediaTimeTable
Parameters
theMedia

The media for this operation. Your application obtains this identifier from such functions as NewTrackMedia and GetTrackMedia.

offsets

A handle to an unlocked relocatable memory block allocated by your application. The function returns the time table for the media in this block.

startTime

The first point of the media to be included in the time table. This time value is expressed in the media's time coordinate system.

endTime

The last point of the media to be included in the time table. This time value is expressed in the media's time coordinate system.

timeIncrement

The resolution of the time table. The values in a time table are for a points in the media, and these points are separated by the amount of time specified by this parameter. The time value is expressed in the media's time coordinate system.

firstDataRefIndex

An index to the first data reference for the media to be included in the time table. Set this parameter to -1 to include all data references for the media. Set this parameter to 1 to specify the first data reference for the media.

lastDataRefIndex

An index to the last data reference for the media to be included in the time table. The value 1 specifies the first data reference for the media. If the value of the firstDataRefIndex parameter is -1, set this parameter to 0.

retdataRefSkew

The offset to the next row of the time table, in long integers. The next row contains values for the next data reference, as explained below. By adding the value of this parameter to an offset into the table, you get the offset to the corresponding point for the next data reference.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Your application must allocate an unlocked relocatable memory block for the time table to be returned and pass a handle to it in the offsets parameter. The MakeMediaTimeTable function resizes the block to accommodate the time table it returns.

This time table is a two-dimensional array of long integers, organized so that each row in the table contains values for one data reference. The first column in the table contains values for the time in the media specified by the startTime parameter, and each subsequent column contains values for the point in the media that is later by the value specified by the timeIncrement parameter. Each long integer value in the table specifies the offset, in bytes, from the beginning of the data reference for that point in the media. The number of columns in the table is equal to (endTime - startTime) / timeIncrement, rounded up. Because of alignment issues, this value is not always the same as the value of the retdataRefSkew parameter.

Special Considerations

When all the data for a movie has been transferred, your application must dispose of the time table created by this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

MakeTrackTimeTable

Returns a time table for a specified track in a movie.

OSErr MakeTrackTimeTable (
   Track trackH,
   long **offsets,
   TimeValue startTime,
   TimeValue endTime,
   TimeValue timeIncrement,
   short firstDataRefIndex,
   short lastDataRefIndex,
   long *retdataRefSkew
);
Parameters
trackH

The track for the operation. Your application gets this identifier from such functions as NewMovieTrack and GetMovieTrack.

offsets

A handle to an unlocked relocatable memory block allocated by your application. The function returns the time table for the track in this block.

startTime

The first point of the track to be included in the time table. This time value is expressed in the movie's time coordinate system.

endTime

The last point of the track to be included in the time table. This time value is expressed in the movie's time coordinate system.

timeIncrement

The resolution of the time table. The values in a time table are for a points in the track, and these points are separated by the amount of time specified by this parameter. The time value is expressed in the movie's time coordinate system.

firstDataRefIndex

An index to the first data reference for the track to be included in the time table. Set this parameter to -1 to include all data references for the track. Set this parameter to 1 to specify the first data reference for the track.

lastDataRefIndex

An index to the last data reference for the track to be included in the time table. The value 1 specifies the first data reference for the track. If the value of the firstDataRefIndex parameter is -1, set this parameter to 0.

retdataRefSkew

The offset to the next row of the time table, as a long integer. The next row contains values for the next data reference, as explained below. By adding the value of this parameter to an offset into the table, you get the offset to the corresponding point for the next data reference.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Your application must allocate an unlocked relocatable memory block for the time table to be returned and pass a handle to it in the offsets parameter. The MakeTrackTimeTable function resizes the block to accommodate the time table it returns.

This time table is a two-dimensional array of long integers that is organized so that each row in the table contains values for one data reference. The first column in the table contains values for the time in the track specified by the startTime parameter, and each subsequent column contains values for the point in the track that is later by the value specified by the timeIncrement parameter. Each long integer value in the table specifies the offset, in bytes, from the beginning of the data reference for that point in the track. The number of columns in the table is equal to (endTime - startTime) / timeIncrement, rounded up. Because of alignment issues, this value is not always the same as the value of the retdataRefSkew parameter. If there are track edits for a track, they are reflected in the track's time table.

Special Considerations

When all the data for a movie has been transferred, your application must dispose of the time table created by this function.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

MovieAudioExtractionBegin

Begins a movie audio extraction session.

OSStatus MovieAudioExtractionBegin (
   Movie m,
   UInt32 flags,
   MovieAudioExtractionRef *outSession
);
Parameters
m

The movie for this operation. Your application obtains this movie identifier from such functions as NewMovie, NewMovieFromProperties, NewMovieFromFile, and NewMovieFromHandle.

flags

Reserved; must be 0.

outSession

A pointer to an opaque session object.

Return Value

An error code. Returns noErr if there is no error.

Discussion

You must call this function before doing any movie audio extraction, because you will pass the object returned by outSession to the other movie audio extraction functions. The format of the extracted audio defaults to the summary channel layout of the movie (all right channels mixed together, all left surround channels mixed together, and so on.), 32-bit float, de-interleaved, with the sample rate set to the highest sample rate found in the movie. You can set the audio format to be something else, as long as it is uncompressed and you do it before your first call to MovieAudioExtractionFillBuffer.

Availability
Related Sample Code
Declared In
Movies.h

MovieAudioExtractionEnd

Ends a movie audio extraction session.

OSStatus MovieAudioExtractionEnd (
   MovieAudioExtractionRef session
);
Parameters
session

The session object returned by MovieAudioExtractionBegin.

Return Value

An error code. Returns noErr if there is no error.

Discussion

You must call this function when movie audio extraction is complete.

Availability
Related Sample Code
Declared In
Movies.h

MovieAudioExtractionFillBuffer

Extracts audio from a movie.

OSStatus MovieAudioExtractionFillBuffer (
   MovieAudioExtractionRef session,
   UInt32 *ioNumFrames,
   AudioBufferList *ioData,
   UInt32 *outFlags
);
Parameters
session

The session object returned by MovieAudioExtractionBegin.

ioNumFrames

A pointer to the number of PCM frames to be extracted.

ioData

A pointer to an AudioBufferList allocated by the caller to hold the extracted audio data.

outFlags

A bit flag that indicates when extraction is complete: kMovieAudioExtractionComplete The extraction process is complete. Value is (1L << 0). See these constants:

Return Value

An error code. Returns noErr if there is no error.

Discussion

You call this function repeatedly; each call continues extracting audio where the last call left off. The function will extract as many of the requested PCM frames as it can, given the limits of the buffer supplied and the limits of the input movie. ioNumFrames will be updated with the exact number of valid frames being returned. When there is no more audio to extract from the movie, the function will continue to return noErr but will return no further audio data. In this case, the outFlags parameter will have its kMovieAudioExtractionComplete bit set. It is possible that the kMovieAudioExtractionComplete bit will accompany the last buffer of valid data.

Availability
Related Sample Code
Declared In
Movies.h

MovieAudioExtractionGetProperty

Gets a property of a movie audio extraction session.

OSStatus MovieAudioExtractionGetProperty (
   MovieAudioExtractionRef session,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   QTPropertyValuePtr outPropValueAddress,
   ByteCount *outPropValueSizeUsed
);
Parameters
session

The session object returned by MovieAudioExtractionBegin.

inPropClass

Pass the following constant to define the property class: Property of an audio presentation; value is 'audi'.

inPropID

Pass one of these constants to define the property ID: kAudioPropertyID_ChannelLayout The summary audio channel layout of a movie, or any other grouping of audio streams. All like-labeled channels are combined, without duplicates. For example, if there is a stereo (L/R) track, 5 single-channel tracks marked Left, Right, Left Surround, Right Surround and Center, and a 4-channel track marked L/R/Ls/Rs, then the summary AudioChannelLayout will be L/R/Ls/Rs/C, not L/R/L/R/Ls/Rs/C/L/R/Ls/Rs. The value of this constant is 'clay'. See these constants:

inPropValueSize

The size of the buffer allocated to receive the property value.

outPropValueAddress

A pointer to the buffer allocated to receive the property value.

outPropValueSizeUsed

The actual size of the property value.

Return Value

An error code. Returns noErr if there is no error.

Availability
Related Sample Code
Declared In
Movies.h

MovieAudioExtractionGetPropertyInfo

Gets information about a property of a movie audio extraction session.

OSStatus MovieAudioExtractionGetPropertyInfo (
   MovieAudioExtractionRef session,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   QTPropertyValueType *outPropType,
   ByteCount *outPropValueSize,
   UInt32 *outPropertyFlags
);
Parameters
session

The session object returned by MovieAudioExtractionBegin.

inPropClass

Pass the following constant to define the property class: Property of an audio presentation; value is 'audi'

inPropID

Pass one of these constants to define the property ID: kAudioPropertyID_ChannelLayout The summary audio channel layout of a movie, or any other grouping of audio streams. All like-labeled channels are combined, without duplicates. For example, if there is a stereo (L/R) track, 5 single-channel tracks marked Left, Right, Left Surround, Right Surround and Center, and a 4-channel track marked L/R/Ls/Rs, then the summary AudioChannelLayout will be L/R/Ls/Rs/C, not L/R/L/R/Ls/Rs/C/L/R/Ls/Rs. The value of this constant is 'clay'. See these constants:

outPropType

A pointer to the type of the returned property's value.

outPropValueSize

A pointer to the size of the returned property's value.

outPropFlags

On return, a pointer to flags representing the requested information about the item's property.

Return Value

An error code. Returns noErr if there is no error.

Availability
Related Sample Code
Declared In
Movies.h

MovieAudioExtractionSetProperty

Sets a property of a movie audio extraction session.

OSStatus MovieAudioExtractionSetProperty (
   MovieAudioExtractionRef session,
   QTPropertyClass inPropClass,
   QTPropertyID inPropID,
   ByteCount inPropValueSize,
   ConstQTPropertyValuePtr inPropValueAddress
);
Parameters
session

The session object returned by MovieAudioExtractionBegin.

inPropClass

Pass the following constant to define the property class: Property of an audio presentation; value is 'audi'.

inPropID

Pass one of these constants to define the property ID: kAudioPropertyID_SummaryChannelLayout The summary audio channel layout of a movie, or any other grouping of audio streams. All like-labeled channels are combined, without duplicates. For example, if there is a stereo (L/R) track, 5 single-channel tracks marked Left, Right, Left Surround, Right Surround and Center, and a 4-channel track marked L/R/Ls/Rs, then the summary AudioChannelLayout will be L/R/Ls/Rs/C, not L/R/L/R/Ls/Rs/C/L/R/Ls/Rs. The value of this constant is 'clay'. See these constants:

inPropValueSize

The size of the property value.

inPropValueAddress

A const void pointer that points to the property value.

Return Value

An error code. Returns noErr if there is no error.

Availability
Related Sample Code
Declared In
Movies.h

MovieExecuteWiredActions

Undocumented

OSErr MovieExecuteWiredActions (
   Movie theMovie,
   long flags,
   QTAtomContainer actions
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

flags

Undocumented See these constants:

  • movieExecuteWiredActionDontExecute

actions

Undocumented

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 4.

Availability
Declared In
Movies.h

MovieSearchText

Searches for text in a movie.

OSErr MovieSearchText (
   Movie theMovie,
   Ptr text,
   long size,
   long searchFlags,
   Track *searchTrack,
   TimeValue *searchTime,
   long *searchOffset
);
Parameters
theMovie

A movie identifier. Your application obtains this identifier from such functions as NewMovie, NewMovieFromFile, and NewMovieFromHandle.

text

The text to be searched for.

size

The size of the text.

searchFlags

Flags (see below) that narrow the search process. See these constants:

  • searchTextDontGoToFoundTime

  • searchTextDontHiliteFoundText

  • searchTextOneTrackOnly

  • searchTextEnabledTracksOnly

searchTrack

On return, a pointer to the found track.

searchTime

On return, a pointer to the found time.

searchOffset

On return, a pointer to the found offset to the text.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

NewActionsUPP

Allocates a Universal Procedure Pointer for ActionsProc.

ActionsUPP NewActionsUPP (
   ActionsProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewActionsProc.

Availability
Declared In
Movies.h

NewDoMCActionUPP

Allocates a Universal Procedure Pointer for the DoMCActionProc callback.

DoMCActionUPP NewDoMCActionUPP (
   DoMCActionProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewDoMCActionProc.

Availability
Declared In
Movies.h

NewGetMovieUPP

Allocates a Universal Procedure Pointer for the GetMovieProc callback.

GetMovieUPP NewGetMovieUPP (
   GetMovieProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewGetMovieProc.

Availability
Declared In
Movies.h

NewMovieController

Locates a movie controller component and assigns a movie to that controller.

ComponentInstance NewMovieController (
   Movie theMovie,
   const Rect *movieRect,
   long someFlags
);
Parameters
theMovie

The movie to be associated with the movie controller.

movieRect

A pointer to the Rect structure that is to define the display boundaries of the movie and its controller.

someFlags

Contains flags (see below) that control the operation. If you set these flags to 0, the movie controller component centers the movie in the rectangle specified by the movieRect parameter and scales the movie to fit in that rectangle. The control portion of the controller is also placed within that rectangle. You may control how the movie and the control are drawn by setting one or more flags to 1. See these constants:

  • mcTopLeftMovie

  • mcScaleMovieToFit

  • mcWithBadge

  • mcNotVisible

  • mcWithFrame

Return Value

The ID of the new controller.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

NewMovieDrawingCompleteUPP

Allocates a Universal Procedure Pointer for the MovieDrawingCompleteProc callback.

MovieDrawingCompleteUPP NewMovieDrawingCompleteUPP (
   MovieDrawingCompleteProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMovieDrawingCompleteProc.

Availability
Related Sample Code
Declared In
Movies.h

NewMovieExecuteWiredActionsUPP

Allocates a Universal Procedure Pointer for the MovieExecuteWiredActionsProc callback.

MovieExecuteWiredActionsUPP NewMovieExecuteWiredActionsUPP (
   MovieExecuteWiredActionsProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMovieExecuteWiredActionsProc.

Availability
Declared In
Movies.h

NewMovieForDataRefFromHandle

Creates a movie from a public movie handle, converting internal references to external references.

OSErr NewMovieForDataRefFromHandle (
   Movie *theMovie,
   Handle h,
   short newMovieFlags,
   Boolean *dataRefWasChanged,
   Handle dataRef,
   OSType dataRefType
);
Parameters
theMovie

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.

h

A handle to the movie resource from which the movie is to be loaded.

newMovieFlags

Constants (see below) that control characteristics of the new movie. Set unused flags to 0. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The toolbox sets the value to TRUE if any references were changed. Pass NIL if you don't want to receive this information.

dataRef

A data reference to the storage from which the movie was retrieved.

dataRefType

The data reference type. See Data References.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function creates a movie from a public movie handle in the same way as NewMovieFromHandle, but with one difference. If the public handle contains internal media data references, the function can convert them to external references, as specified by dataRef and dataRefType. No other data references are changed.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

NewMovieFromDataFork

Retrieves a movie that is stored anywhere in the data fork of a specified Macintosh file.

OSErr NewMovieFromDataFork (
   Movie *theMovie,
   short fRefNum,
   long fileOffset,
   short newMovieFlags,
   Boolean *dataRefWasChanged
);
Parameters
theMovie

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.

fRefNum

A file reference number to a file that is already open.

fileOffset

The starting file offset of the atom in the data fork of the file specified by the fRefNum parameter.

newMovieFlags

Flags (see below) that control characteristics of the new movie. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The Movie Toolbox sets the value to TRUE if any of the movie's data references were changed. Use UpdateMovieResource to preserve these changes. If you do not want to receive this information, set the dataRefWasChanged parameter to NIL.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access error returns such as this through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

NewMovieFromDataFork64

Provides a 64-bit version of NewMovieFromDataFork.

OSErr NewMovieFromDataFork64 (
   Movie *theMovie,
   long fRefNum,
   const wide *fileOffset,
   short newMovieFlags,
   Boolean *dataRefWasChanged
);
Parameters
theMovie

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.

fRefNum

A file reference number to a file that is already open.

fileOffset

A pointer to the starting file offset of the atom in the data fork of the file specified by the fRefNum parameter.

newMovieFlags

Flags (see below) that control characteristics of the new movie. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The Movie Toolbox sets the value to TRUE if any of the movie's data references were changed. Use UpdateMovieResource to preserve these changes. If you do not want to receive this information, set the dataRefWasChanged parameter to NIL.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access error returns such as this through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 4. Superseded in QuickTime 6 by NewMovieFromStorageOffset.

Availability
Declared In
Movies.h

NewMovieFromDataRef

Creates a movie from any device with a corresponding data handler.

OSErr NewMovieFromDataRef (
   Movie *m,
   short flags,
   short *id,
   Handle dataRef,
   OSType dataRefType
);
Parameters
m

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.

flags

Flags (see below) that control the operation of this function. Be sure to set unused flags to 0. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

id

A pointer to the field that specifies the resource containing the movie data that is to be loaded. If the field referred to by the id 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 id parameter. An enumerated constant (see below) is available. See these constants:

  • movieInDataForkResID

dataRef

The default data reference. This parameter contains a handle to the information that identifies the file to be used to resolve any data references and as a starting point for any Alias Manager searches. The type of information stored in the handle depends upon the value of the dataRefType parameter. For example, if your application is loading the movie from a file, you would refer to the file's alias in this parameter and set the dataRefType parameter to rAliasType. If you do not want to identify a default data reference, set the parameter to NIL.

dataRefType

The type of data reference. If the data reference is an alias, you must set the parameter to rAliasType, indicating that the reference is an alias.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access error returns such as this through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function is intended for use by specialized applications that need to instantiate movies from devices not visible to the file system. Most applications should continue to use NewMovieFromFile. You are not restricted to instantiating a movie from a file stored on a Macintosh HFS volume. With this function, you can instantiate a movie from any device.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

NewMovieFromFile

Creates a new movie in memory from a movie file or from any type of file for which QuickTime provides an import component (AIFF, JPEG, MPEG-4, etc).

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

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

The movie file from which the movie is to be loaded. Your application obtains this value from the OpenMovieFile function.

resId

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 Movie Toolbox then returns the movie's resource ID number in the field referred to by the resId parameter. An enumerated constant (see below) is available. See these constants:

  • movieInDataForkResID

resName

A pointer 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 Movie Toolbox does not return the resource name.

newMovieFlags

Flags (see below) that control the operation of NewMovieFromFile. Be sure to set unused flags to 0. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The Movie Toolbox sets the value to TRUE if any references were changed. Use UpdateMovieResource to preserve these changes. Set this parameter to NIL if you don't want to receive this information. See NewMovieTrack for more information about data references.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access error returns such as this through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

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

The following is an example of using this function:

// NewMovieFromFile coding example
// See "Discovering QuickTime," page 385
Movie MyGetMovie (void)
{
    OSErr                   nErr;
    SFTypeList              types ={MovieFileType, 0, 0, 0};
    StandardFileReply       sfr;
    Movie                   movie =NIL;
    short                   nFileRefNum;
    StandardGetFilePreview(NIL, 1, types, &sfr);
    if (sfr.sfGood) {
        nErr =OpenMovieFile(&sfr.sfFile, &nFileRefNum, fsRdPerm);
        if (nErr ==noErr) {
            short           nResID =0;         //We want the first movie.
            Str255          strName;
            Boolean         bWasChanged;
 
            nErr =NewMovieFromFile(&movie, nFileRefNum, &nResID, strName,
                                    newMovieActive, &bWasChanged);
            CloseMovieFile(nFileRefNum);
        }
    }
    return movie;
}
Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Special Considerations

This function works with some files that don't contain movie resources. When it encounters a file that does not contain a movie resource, it tries to find a movie import component that can understand the data and create a movie. It also works for MPEG, uLaw (.AU), and Wave (.WAV) file types. In some cases, the data in a file is already sufficiently well formatted for QuickTime or its components to understand. For example, the AIFF movie data import component can understand AIFF sound files and import the sound data into a QuickTime movie.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

NewMovieFromHandle

Creates a movie in memory from a movie resource or a handle you obtained from PutMovieIntoHandle.

OSErr NewMovieFromHandle (
   Movie *theMovie,
   Handle h,
   short newMovieFlags,
   Boolean *dataRefWasChanged
);
Parameters
theMovie

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.

h

A handle to the movie resource from which the movie is to be loaded.

newMovieFlags

Flags (see below) that control the operation of NewMovieFromHandle. Be sure to set unused flags to 0. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The toolbox sets the value to TRUE if any references were changed. Set the dataRefWasChanged parameter to NIL if you don't want to receive this information.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access error returns such as this through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

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 NewMovieFromHandle. To change the graphics world for the new movie, your application should use SetMovieGWorld.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

NewMovieFromScrap

Creates a movie from the contents of the scrap.

Movie NewMovieFromScrap (
   long newMovieFlags
);
Parameters
newMovieFlags

Flags (see below) that control the operation of the NewMovieFromScrap function. Be sure to set unused flags to 0. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

Return Value

The identifier for the new movie. If NewMovieFromScrap fails, or if there is no movie in the scrap, the returned identifier is set to NIL. You can use GetMoviesError to obtain the error result, or noErr if there was no error. See Error Codes.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

NewMovieFromStorageOffset

Creates a new movie based on the offset to data in a storage container.

OSErr NewMovieFromStorageOffset (
   Movie *theMovie,
   DataHandler dh,
   const wide *fileOffset,
   short newMovieFlags,
   Boolean *dataRefWasChanged
);
Parameters
theMovie

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

dh

The data handler component that was returned by CreateMovieStorage. The data handler's file must be open.

fileOffset

A pointer to the location of the movie data in the storage location specified by the dh parameter. Unlike NewMovieFromDataFork and NewMovieFromDataFork64, there is no special meaning to a file offset of -1.

newMovieFlags

Constants (see below) that control characteristics of the new movie. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The Movie Toolbox sets the value to TRUE if any of the movie's data references were changed. Use UpdateMovieInStorage to preserve these changes. If you do not want to receive this information, pass NIL.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

This function serves the same purpose for data handlers as NewMovieFromDataFork64 does for movie file references. The API reads the 'moov' resource found at fileOffset and creates a Movie. The data handler parameter should be an open data handler component instance for the storage holding the 'moov' resource. The newMovieFlags and dataRefWasChanged parameters are interpreted identically to those same parameters in NewMovieFromDataFork64.

If you are writing a custom data handler, make sure it implements DataHGetDataRef. Also implement DataHScheduleData64 and DataHGetFileSize64, or DataHScheduleData and DataHGetFileSize if the data handler does not support 64-bit file offsets.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 6. Supersedes NewMovieFromDataFork64.

Availability
Declared In
Movies.h

NewMovieFromUserProc

Creates a movie from data that you provide.

OSErr NewMovieFromUserProc (
   Movie *m,
   short flags,
   Boolean *dataRefWasChanged,
   GetMovieUPP getProc,
   void *refCon,
   Handle defaultDataRef,
   OSType dataRefType
);
Parameters
m

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.

flags

Flags (see below) that control the operation of the NewMovieFromUserProc function. Be sure to set unused flags to 0. See these constants:

  • newMovieActive

  • newMovieDontResolveDataRefs

  • newMovieDontAskUnresolvedDataRefs

dataRefWasChanged

A pointer to a Boolean value. The Toolbox sets the value to TRUE if any references were changed. Use UpdateMovieResource to preserve these changes. Set the dataRefWasChanged parameter to NIL if you don't want to receive this information.

getProc

A Universal Procedure Pointer that accesses a GetMovieProc callback, which is responsible for providing the movie data to the Movie Toolbox.

refCon

A reference constant (defined as a void pointer). This is the same value you provided to the Movie Toolbox when you called NewMovieFromUserProc. Use this parameter to point to a data structure containing any information your callback needs.

defaultDataRef

The default data reference. This parameter contains a handle to the information that identifies the file to be used to resolve any data references and as a starting point for any Alias Manager searches. The type of information stored in the handle depends upon the value of the dataRefType parameter. For example, if your application is loading the movie from a file, you would refer to the file's alias in the defaultDataRef parameter, and set the dataRefType parameter to rAliasType. If you don't want to identify a default data reference, set the parameter to NIL.

dataRefType

The type of data reference. If the data reference is an alias, you must set the parameter to rAliasType, indicating that the reference is an alias.

Return Value

If the Movie Toolbox cannot completely resolve all data references, it sets the current error value to couldNotResolveDataRef. You can access error returns such as this through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

Normally, when a movie is loaded from a file (for example, by means of NewMovieFromFile), the Movie Toolbox uses that file as the default data reference. Since this function does not require a file specification, your application should specify the file to be used as the default data reference using the defaultDataRef and dataRefType parameters.

Special Considerations

The Movie Toolbox automatically sets the movie's graphics world based on the current graphics port. Be sure that your application's graphics port is valid before you call this function, even if the movie is sound-only; you can use GetGWorld to check for a valid port, or you can use NewGWorld to create a port. The graphics port must remain valid for the life of the movie or until you set another valid graphics port for the movie using SetMovieGWorld.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Declared In
Movies.h

NewMoviePrePrerollCompleteUPP

Allocates a Universal Procedure Pointer for the MoviePrePrerollCompleteProc callback.

MoviePrePrerollCompleteUPP NewMoviePrePrerollCompleteUPP (
   MoviePrePrerollCompleteProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMoviePrePrerollCompleteProc.

Availability
Related Sample Code
Declared In
Movies.h

NewMoviePreviewCallOutUPP

Allocates a Universal Procedure Pointer for the MoviePreviewCallOutProc callback.

MoviePreviewCallOutUPP NewMoviePreviewCallOutUPP (
   MoviePreviewCallOutProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMoviePreviewCallOutProc.

Availability
Declared In
Movies.h

NewMovieProgressUPP

Allocates a Universal Procedure Pointer for the MovieProgressProc callback.

MovieProgressUPP NewMovieProgressUPP (
   MovieProgressProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMovieProgressProc.

Availability
Declared In
Movies.h

NewMovieRgnCoverUPP

Allocates a Universal Procedure Pointer for the MovieRgnCoverProc callback.

MovieRgnCoverUPP NewMovieRgnCoverUPP (
   MovieRgnCoverProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMovieRgnCoverProc.

Availability
Related Sample Code
Declared In
Movies.h

NewMoviesErrorUPP

Allocates a Universal Procedure Pointer for the MoviesErrorProc callback.

MoviesErrorUPP NewMoviesErrorUPP (
   MoviesErrorProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Version Notes

Introduced in QuickTime 4.1. Replaces NewMoviesErrorProc.

Availability
Declared In
Movies.h

NewQTCallBackUPP

Allocates a Universal Procedure Pointer for the QTCallBackProc callback.

QTCallBackUPP NewQTCallBackUPP (
   QTCallBackProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewQTCallBackProc.

Availability
Declared In
Movies.h

NewQTEffectListFilterUPP

Allocates a Universal Procedure Pointer for the QTEffectListFilterProc callback.

QTEffectListFilterUPP NewQTEffectListFilterUPP (
   QTEffectListFilterProcPtr userRoutine
);
Parameters
userRoutine

A pointer to a QTEffectListFilterProc callback.

Return Value

A new UPP; see Universal Procedure Pointers.

Version Notes

Introduced in QuickTime 6.

Availability
Declared In
Movies.h

NewQTNextTaskNeededSoonerCallbackUPP

Allocates a Universal Procedure Pointer for the QTNextTaskNeededSoonerCallbackProc callback.

QTNextTaskNeededSoonerCallbackUPP NewQTNextTaskNeededSoonerCallbackUPP (
   QTNextTaskNeededSoonerCallbackProcPtr userRoutine
);
Parameters
userRoutine

A pointer to a QTNextTaskNeededSoonerCallbackProc callback.

Return Value

A new UPP; see Universal Procedure Pointers.

Version Notes

Introduced in QuickTime 6.

Availability
Related Sample Code
Declared In
Movies.h

NewQTSyncTaskUPP

Allocates a Universal Procedure Pointer for the QTSyncTaskProc callback.

QTSyncTaskUPP NewQTSyncTaskUPP (
   QTSyncTaskProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces NewQTSyncTaskProc.

Availability
Declared In
Movies.h

NewSprite

Creates a new sprite in a specified sprite world.

OSErr NewSprite (
   Sprite *newSprite,
   SpriteWorld itsSpriteWorld,
   ImageDescriptionHandle idh,
   Ptr imageDataPtr,
   MatrixRecord *matrix,
   Boolean visible,
   short layer
);
Parameters
newSprite

A pointer to field that is to receive the new sprite's identifier. On return, this field contains the identifier of the newly created sprite.

itsSpriteWorld

The sprite world with which the new sprite should be associated.

idh

A handle to an ImageDescription structure of the sprite's image.

imageDataPtr

A pointer to the sprite's image data.

matrix

A pointer to the sprite's MatrixRecord structure. If you pass NIL, an identity matrix is assigned to the sprite.

visible

Specifies whether the sprite is visible.

layer

The sprite's layer. Sprites with lower layer values appear in front of sprites with higher layer values. If you want to create a sprite that is drawn to the background graphics world, you should specify the constant kBackgroundSpriteLayerNum for the layer parameter.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

The visible parameter, the layer parameter, and the newSprite and itsSpriteWorld parameters are required. You can defer assigning image data to the sprite by passing NIL for both the idh and imageDataPtr parameters. If you choose to defer assigning image data, you must call SetSpriteProperty to assign the image description handle and image data to the sprite before the next call to SpriteWorldIdle.

Special Considerations

The caller owns the image description handle and the image data pointer; it is the caller's responsibility to dispose of them after it disposes of a sprite.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

NewSpriteWorld

Creates a new sprite world.

OSErr NewSpriteWorld (
   SpriteWorld *newSpriteWorld,
   GWorldPtr destination,
   GWorldPtr spriteLayer,
   RGBColor *backgroundColor,
   GWorldPtr background
);
Parameters
newSpriteWorld

A pointer to a field that is to receive the new sprite world's identifier. On return, this field contains the identifier for the newly created sprite world.

destination

A pointer to a CGrafPort structure that defines the graphics world to be used as the destination.

spriteLayer

A pointer to a CGrafPort structure that defines the graphics world to be used as the sprite layer.

backgroundColor

A pointer to an RGBColor structure that defines the color to be used as the background color. If you pass a background graphics world to this function by setting the background parameter, you can set this parameter to NIL.

background

A pointer to a CGrafPort structure that defines the graphics world to be used as the background. If you pass a background color to this function by setting the backgroundColor parameter, you can set this parameter to NIL.

Return Value

You can access Movie Toolbox error returns through GetMoviesError and GetMoviesStickyError, as well as in the function result. See Error Codes.

Discussion

You call this function to create a new sprite world with associated destination and sprite layer graphics worlds, and either a background color or a background graphics world. Once created, you can manipulate the sprite world and add sprites to it using other sprite Movie Toolbox functions.

The newSpriteWorld, destination, and spriteLayer parameters are all required. You should specify a background color, a background graphics world, or both. You should not pass NIL for both parameters. If you specify both a background graphics world and a background color, the sprite world is filled with the background color before the background sprites are drawn. If no background color is specified, black is the default. If you specify a background graphics world, it should have the same dimensions and depth as the graphics world specified by spriteLayer. If you draw to the graphics worlds associated with a sprite world using standard QuickDraw and QuickTime functions, your drawing is erased by the sprite world's background color. The sprite world created by this function has an identity matrix and does not have a clip shape.

Here is an example of creating a sprite world:

// NewSpriteWorld coding example
// See "Discovering QuickTime," page 166
GWorldPtr       pSpritePlane =NIL;
SpriteWorld     spriteWorld =NIL;
Rect            rectBounce;
RGBColor        rgbcBackground;
void CreateSpriteStuff (Rect *pWndRect, CGrafPtr pMacWnd)
{
    OSErr       nErr;
    Rect        rect;
    // calculate the size of the destination
    rect =*pWndRect;
    OffsetRect(&rect, -rect.left, -rect.top);
    rectBounce =rect;
    InsetRect(&rectBounce, 16, 16);
    // create a sprite graphics world with a bit depth of 16
    NewGWorld(&pSpritePlane, 16, &rect, NIL, NIL, useTempMem);
    if (pSpritePlane ==NIL)
        NewGWorld(&pSpritePlane, 16, &rect, NIL, NIL, 0);
    if (pSpritePlane !=NIL) {
        LockPixels(pSpritePlane->
portPixMap);
        rgbcBackground.red =
        rgbcBackground.green =
        rgbcBackground.blue =0;
        // create a sprite world
        nErr =NewSpriteWorld(&spriteWorld, (CGrafPtr)pMacWnd,
            pSpritePlane, &rgbcBackground, NIL);
    }
}
Special Considerations

Before calling this function, you should lock the pixel maps of the sprite layer and background graphics worlds. These graphics worlds must remain valid and locked for the lifetime of the sprite world. The sprite world does not own the graphics worlds that are associated with it; it is the caller's responsibility to dispose of the graphics worlds when they are no longer needed.

Version Notes

Introduced in QuickTime 3 or earlier.

Availability
Related Sample Code
Declared In
Movies.h

NewTextMediaUPP

Allocates a Universal Procedure Pointer for the TextMediaProc callback.

TextMediaUPP NewTextMediaUPP (
   TextMediaProcPtr userRoutine
);
Parameters
userRoutine

A pointer to your application-defined function.

Return Value

A new UPP; see Universal Procedure Pointers.

Discussion

This function is used with Macintosh PowerPC systems. See Inside Macintosh: PowerPC System Software.

Version Notes

Introduced in QuickTime 4.1. Replaces