Importing Movie Data

Movie data import components may provide one or two functions that allow the Movie Toolbox to request a data conversion operation. The MovieImportHandle function instructs your component to retrieve the data that is to be imported from a specified handle. The MovieImportFile function instructs you to retrieve the data from a file. You should set the appropriate flags in your component’s componentFlags field to indicate which of these functions your component supports. Note that your component may support both functions.

Before the Movie Toolbox calls one of these functions, a requesting application may call one or more of your component’s configuration functions (see Configuring Movie Data Import Components for more information about these functions). However, your component should work properly even if none of these configuration functions is called.

Exporting Movie Data

Movie data export components may provide one or two functions that allow the Movie Toolbox to request a data conversion operation. The MovieExportToHandle function instructs your component to place the converted data into a specified handle. The MovieExportToFile function instructs you to put the data into a file. You should set the appropriate flags in your component’s componentFlags field to indicate which of these functions your component supports. Note that your component may support both functions.

Before the Movie Toolbox calls one of these functions, a requesting application may call one or more of your component’s configuration functions (see Configuring Movie Data Export Components for more information about these functions). However, your component should work properly even if none of these configuration functions is called.

Summary of Constants

/* component type values */

#define MovieImportType                   'eat '    /* movie data import */

#define MovieExportType                   'spit'    /* movie data export */

/*  componentFlags values for movie import and movie export components */

enum {

    canMovieImportHandles                = 1,    /* can import from handles */

    canMovieImportFiles                  = 2,    /* can import from files */

    hasMovieImportUserInterface          = 4,    /* import has user interface */

    canMovieExportHandles                = 8,    /* can export to handles */

    canMovieExportFiles                  = 16,   /* can export to files */

    hasMovieExportUserInterface          = 32,   /* export has user interface */

    dontAutoFileMovieImport              = 64    /* do not automatically

                                                      import movie files */

};

/*  flags for MovieImportHandle and MovieImportFile */

enum {

    movieImportCreateTrack                 = 1,    /* create a new track */

    movieImportInParallel                  = 2,    /* paste imported data */

    movieImportMustUseTrack                = 4     /* use specified track */

};

enum {

    movieImportResultUsedMultipleTracks    = 8,    /* component used

                                                      several tracks */

};

enum {

    /* movie data import components */

    kMovieImportHandleSelect                = 1,  /* import from handle */

    kMovieImportFileSelect                  = 2,  /* import from file */

    kMovieImportSetSampleDurationSelect     = 3,  /* set sample duration */

    kMovieImportSetSampleDescriptionSelect  = 4,  /* set sample description */

    kMovieImportSetMediaFileSelect          = 5,  /* set media file */

    kMovieImportSetDimensionsSelect         = 6,  /* set track dimensions */

    kMovieImportSetChunkSizeSelect          = 7,  /* set chunk size */

    kMovieImportSetProgressProcSelect       = 8,  /* set progress func */

    kMovieImportSetAuxiliaryDataSelect      = 9,  /* set additional data */

    kMovieImportSetFromScrapSelect          = 10, /* data from scrap */

    kMovieImportDoUserDialogSelect          = 11, /* invoke user dialog */

    kMovieImportSetDurationSelect           = 12  /* set paste duration */

    /* movie data export components */

    kMovieExportToHandleSelect             = 128,  /* export to handle */

    kMovieExportToFileSelect               = 129,  /* export to file */

    kMovieExportDoUserDialogSelect         = 130,  /* invoke user dialog */

    kMovieExportGetAuxiliaryDataSelect     = 131,  /* get additional data */

    kMovieExportSetProgressProcSelect      = 132   /* set progress function */

};

Result Codes

A Sample Movie Import Component

This section describes how to create a movie import component. First, you implement the required functions. Then, you instruct your component to obtain the movie data from a handle or a file. This section supplies a sample program that implements a movie data exchange component that imports a Scrapbook file containing QuickDraw PICT images.

Your movie data import component may provide a user dialog box. You may use this dialog box in any way that is appropriate for your component; for example, to obtain certain parameter information governing the import operation, such as the image-compression method.

In addition, the requesting application may use one or more of the configuration functions to establish parameters for the import operation.

You should not rely on any outside configuration information. Your component should work properly knowing only the source data and the target movie. The Movie Toolbox supplies this information to your component when it calls your MovieImportHandle function or MovieImportFile function.

Your movie data import component may implement either one or both of these functions, which allow the Movie Toolbox to request that data be converted into a format for use in a QuickTime movie.

If the data is to be imported from a handle, the MovieImportHandle function is used.

If data is to be imported from a file, the MovieImportFile function is used.

Set the appropriate flags in your component’s componentFlags field to indicate which of these functions your component supports. Note that your component may support both functions.

Implementing the Required Import Component Functions

Listing 6-1 supplies a sample program that implements a movie data exchange component that imports a Scrapbook file containing QuickDraw PICT images. The sample program also provides the dispatchers for the movie import component together with the required functions.

Listing 6-1  Implementing the required import functions

#define kMediaTimeScale 600

typedef struct {

    ComponentInstance       self

    TimeValue               frameDuration;

} ImportScrapbookGlobalsRecord, **ImportScrapbookGlobals;

/* entry point for all Component Manager requests */

pascal ComponentResult ImportScrapbookDispatcher (ComponentParameters *params,

        Handle storage)

{

    OSErr err = badComponentSelector;

    ComponentFunction componentProc = 0;

    switch (params->what) {

        case kComponentOpenSelect:

            componentProc = ImportScrapbookOpen; break;

        case kComponentCloseSelect:

            componentProc = ImportScrapbookClose; break;

        case kComponentCanDoSelect:

            componentProc = ImportScrapbookCanDo; break;

        case kComponentVersionSelect:

            componentProc = ImportScrapbookVersion; break;

        case kMovieImportFileSelect:

            componentProc = ImportScrapbookFile; break;

        case kMovieImportSetSampleDurationSelect:

            componentProc = ImportScrapbookSetSampleDuration; break;

    }

    if (componentProc)

        err = CallComponentFunctionWithStorage (storage,

     params,

          componentProc);

    return err;

}

pascal ComponentResult ImportScrapbookCanDo

                 (ImportScrapbookGlobals storage, short ftnNumber)

{

    switch (ftnNumber) {

        case kComponentOpenSelect:

        case kComponentCloseSelect:

        case kComponentCanDoSelect:

        case kComponentVersionSelect:

        case kMovieImportFileSelect:

        case kMovieImportSetSampleDurationSelect:

            return true;

        default:

            return false;

    }

}

pascal ComponentResult ImportScrapbookVersion

                                        (ImportScrapbookGlobals storage)

{

    return 0x00010001;

}

pascal ComponentResult ImportScrapbookOpen

                                    (ImportScrapbookGlobals storage,

                                     ComponentInstance self)

{

    storage = (ImportScrapbookGlobals) NewHandleClear

                            (sizeof (ImportScrapbookGlobalsRecord));

    if (!storage) return MemError();

    (**storage).self = self;

    SetComponentInstanceStorage (self, (Handle)storage);

    return noErr;

}

pascal ComponentResult ImportScrapbookClose

                                         (ImportScrapbookGlobals storage,

                                             ComponentInstance self)

{

    if (storage) DisposeHandle((Handle)storage);

    return noErr;

}

/* If this function is called, it provides a hint from the caller as to the

desired sample (frame) duration in the new media */

pascal ComponentResult ImportScrapbookSetSampleDuration

                                         (ImportScrapbookGlobals storage,

                                            TimeValue duration,

                                            TimeScale scale)

{

    TimeRecord tr;

    tr.value.lo = duration;

    tr.value.hi = 0;

    tr.scale = 0;

    tr.base = nil;

    ConvertTimeScale (&tr, kMediaTimeScale);

                    /* your new media will have a time scale of 600 */

    (**storage).frameDuration = tr.value.lo;

    return noErr;

}

pascal ComponentResult ImportScrapbookFile

                                    (ImportScrapbookGlobals storage,

                                     FSSpec *theFile, Movie theMovie,

                                     Track targetTrack, Track *usedTrack,

                                     TimeValue atTime,

                                     TimeValue *addedTime,

                                     long inFlags, long *outFlags)

{

    OSErr err;

    short resRef = 0, saveRes = CurResFile();

    PicHandle thePict;

    Rect trackRect;

    short pageIndex = 0;

    Track newTrack = 0;

    Media newMedia;

    Boolean endMediaEdits = false;

    TimeValue frameDuration;

    SampleDescriptionHandle sampleDesc = 0;

    *outFlags = 0;

    if (inFlags & movieImportMustUseTrack)

        return invalidTrack;

    /* open source file */

    resRef = FSpOpenResFile (theFile, fsRdPerm);

    if (err = ResError()) goto bail;

    UseResFile(resRef);

    /* get the first PICT to determine the track size */

    thePict = (PicHandle)Get1IndResource ('PICT', 1);

    if (!thePict) {

        err = ResError();

        goto bail;

    }

    trackRect = (**thePict).picFrame;

    OffsetRect(&trackRect, -trackRect.left, -trackRect.top);

    /* create a track and PICT media */

    newTrack = NewMovieTrack (theMovie, trackRect.right << 16,

                                     trackRect.bottom << 16, kNoVolume);

    if (err = GetMoviesError()) goto bail;

    newMedia = NewTrackMedia (newTrack, 'PICT', kMediaTimeScale, nil, 0);

    if (err = GetMoviesError()) goto bail;

    if (err = BeginMediaEdits (newMedia)) goto bail;

    endMediaEdits = true;

    /* determine the frame duration (check the hint you may

        have been called with) */

    frameDuration = (**storage).frameDuration;

    if (!frameDuration) frameDuration = kMediaTimeScale/5;

                                        /* default is 1/5th second */

    /* set up a simple sample description */

    sampleDesc = (SampleDescriptionHandle) NewHandleClear

                                            (sizeof (SampleDescription));

    (**sampleDesc).descSize = sizeof(SampleDescription);

    (**sampleDesc).dataFormat = 'PICT';

    /* cycle through all source frames and add them to the media */

    do {

        Handle thePict;

        short resID = pageToMapIndex (++pageIndex,

                                      *GetResource ('SMAP', 0));

        if (resID == 0) break;

        thePict = Get1Resource ('PICT', resID);

        if (thePict == nil) continue;           /* some pages may not

                                                    contain a 'PICT' */

        err = AddMediaSample(newMedia, thePict, 0,

                                    GetHandleSize (thePict),

                                     frameDuration, sampleDesc, 1, 0, nil);

        ReleaseResource (thePict);

        DisposeHandle (thePict);

    } while (!err);

    if (err) goto bail;

    /* add the new media to the track */

    err = InsertMediaIntoTrack (newTrack, 0, 0,

                                GetMediaDuration (newMedia), kFix1);

bail:

    if (resRef) CloseResFile (resRef);

    if (endMediaEdits) EndMediaEdits (newMedia);

    if (err && newTrack) {

        DisposeMovieTrack (newTrack);

        newTrack = 0;

    }

    UseResFile (saveRes);

    if (sampleDesc) DisposeHandle ((Handle)sampleDesc);

    *usedTrack = newTrack;

    return err;

}

/* map from a Scrapbook page number to a resource ID */

short pageToMapIndex (short page, Ptr map)

{

    short mapIndex;

    for (mapIndex = 0; mapIndex < 256; mapIndex++)

        if (*map++ == page)

            return mapIndex | 0x8000;

    return 0;

}

A Sample Movie Export Component

As with movie data import components, the movie data export component should not rely on any configuration information beyond that which is supplied by the Movie Toolbox when it calls the MovieExportToHandle or MovieExportToFile function, respectively.

This section provides an implementation of a movie data exchange component that exports a movie or movie’s track to a PICS animation file.

typedef struct {

    ComponentInstance self;

} ExportPICSGlobalsRecord, *ExportPICSGlobals;

/* entry point for all Component Manager requests */

pascal ComponentResult ExportPICSDispatcher

                                        (ComponentParameters *params,

                                         Handle storage)

{

    OSErr err = badComponentSelector;

    ComponentFunction componentProc = 0;

    switch (params->what) {

        case kComponentOpenSelect:

            componentProc = ExportPICSOpen; break;

        case kComponentCloseSelect:

            componentProc = ExportPICSClose; break;

        case kComponentCanDoSelect:

            componentProc = ExportPICSCanDo; break;

        case kComponentVersionSelect:

            componentProc = ExportPICSVersion; break;

        case kMovieExportToFileSelect:

            componentProc = ExportPICSToFile; break;

    }

    if (componentProc)

        err = CallComponentFunctionWithStorage (storage, params,

                                                componentProc);

    return err;

}

pascal ComponentResult ExportPICSCanDo (ExportPICSGlobals store,

                                                     short ftnNumber)

{

    switch (ftnNumber) {

        case kComponentOpenSelect:

        case kComponentCloseSelect:

        case kComponentCanDoSelect:

        case kComponentVersionSelect:

        case kMovieExportToFileSelect:

            return true;

            break;

        default:

            return false;

            break;

    }

}

pascal ComponentResult ExportPICSVersion (ExportPICSGlobals store)

{

    return 0x00010001;

}

pascal ComponentResult ExportPICSOpen (ExportPICSGlobals store,

                                                     ComponentInstance self)

{

    OSErr err;

    store = (ExportPICSGlobals) NewPtrClear

                (sizeof(ExportPICSGlobalsRecord));

    if (err = MemError()) goto bail;

    store->self = self;

    SetComponentInstanceStorage(self, (Handle)store);

bail:

    return err;

}

pascal ComponentResult ExportPICSClose (ExportPICSGlobals store,

                                        ComponentInstance self)

{

    if (store) DisposPtr((Ptr)store);

    return noErr;

}

pascal ComponentResult ExportPICSToFile (ExportPICSGlobals store,

                                                        const FSSpec *theFile,

                                                        Movie m,

                                                        Track onlyThisTrack,

                                                        TimeValue startTime,

                                                        TimeValue duration)

{

    OSErr err = noErr;

    short resRef = 0;

    short saveResRef = CurResFile();

    short resID = 128;

    PicHandle thePict = nil;

    /* open the resource fork of the PICS file

        (the caller is responsible for creating the file) */

    resRef = FSpOpenResFile (theFile, fsRdWrPerm);

    if (err = ResError()) goto bail;

    UseResFile(resRef);

    /* cycle through the movie time segment you were given */

    while (startTime < duration) {

        Byte c = 0;

        if (onlyThisTrack)

            thePict = GetTrackPict (onlyThisTrack, startTime);

        else

            thePict = GetMoviePict(m, startTime);

        if (!thePict) continue;

        /* add a frame to the PICS file */

        AddResource ((Handle)thePict, 'PICT', resID++, &c);

        err = ResError();

        WriteResource ((Handle)thePict);

        DetachResource ((Handle)thePict);

        KillPicture (thePict);

        thePict = nil;

        if (err) break;

        /* find the time of the next frame */

        do {

            TimeValue nextTime;

            if (onlyThisTrack)

                GetTrackNextInterestingTime (onlyThisTrack,

                                             nextTimeMediaSample, startTime,

                                             kFix1, &nextTime, nil);

            else {

                OSType mediaType = VisualMediaCharacteristic;

                GetMovieNextInterestingTime (m, nextTimeMediaSample,

                                                        1, &mediaType,

                                                        startTime, kFix1,

                                                        &nextTime, nil);

            }

            if (GetMoviesError ()) goto bail;

            if (nextTime != startTime) {

                startTime = nextTime;

                break;

            }

        } while (++startTime < duration);

    }

bail:

    if (thePict) KillPicture (thePict);

    if (resRef) CloseResFile (resRef);

    UseResFile (saveResRef);

    return err;

}

Save-and-Restore Component Routines

If you are writing movie data exchange components, and would like your components' settings to be saved and restored, you need to implement two additional component routines in order to allow your components to have their settings saved and restored. A component’s settings are stored in a QuickTime QT atom container. The data stored in the QT atom container is private to the particular component but should be stored so that it is possible to read the data on all platforms supported by QuickTime, thus allowing the same settings to be used anywhere.

For each type of movie data exchange component, there is one routine to return a QT atom container holding the settings and another routine to configure the component from previously-saved settings. For more information about QT atom containers, see QuickTime Movie Basics.

Import component developers need to implement the MovieImportGetSettingsAsAtomContainer and MovieImportSetSettingsFromAtomContainer routines. For MovieImportGetSettingsAsAtomContainer, the component should allocate a new QT atom container, stuff current settings into it, and return it to the caller. For MovieImportSetSettingsFromAtomContainer, the component should accept a QT atom container, extract the settings in which it is interested, and change its internal state.

Export component developers need to implement the MovieExportGetSettingsAsAtomContainer and MovieExportSetSettingsFromAtomContainer routines. Like import components, the component’s MovieExportGetSettingsAsAtomContainer routine allocates and returns a QT atom container holding the component’s settings. For MovieExportSetSettingsFromAtomContainer, the component accepts a QT atom container, extracts the settings, and updates its internal state.

Settings Container Format and Guidelines

The particular atoms stored within the component’s settings QT atom container are private to that component type. However, there are some guidelines that need to be followed. These include:

In all SetSettingsFromAtomContainer routines, the QT atom container belongs to the caller. The component should not dispose of the passed QT atom container.

The settings QT atom container should contain one or more top-level atoms. These top-level atoms can contain either leaf data or other atoms. Each atom has both a type (QTAtomType) and an ID. Choosing an atom type that is mnemonic is helpful in indicating how it is used. For example, QuickTime stores video compression settings in atoms of type 'vide'. Sound compression settings are stored in 'soun' atoms. The text components use 'text' for their atom types.

Several of QuickTime’s export components use the standard compression component to allow the user to configure compression settings for exported files. When one of these components is asked to return its settings atom container, the export component first requests that the standard compression component return its settings using the SCGetSettingsAsAtomContainer function described above. To the QT atom container it receives, the export component adds any of its own settings. When the export component’s SetSettingsFromAtomContainer is called, the exporter calls

SCSetSettingsFromAtomContainer with the passed atom container. The standard compression component extracts only those settings it expects, ignoring all other, and configures itself. The exporter then looks for its own settings in the same atom container and configures itself.

This is possible because the standard compression and data exchange components both use QT atom containers to hold their settings. Because many third-party developers do the same, there must be a mechanism so that QuickTime’s own top-level atom types and those of third parties don’t collide. To achieve this, Apple Computer reserves all top-level atom types consisting exclusively of lowercase letters with or without numerals. For example, 'vide' is reserved by Apple, but 'Vide' is not. There is no restriction on the atom types for atoms stored within these top-level atoms.

Apple recommends that you store all of your component settings under a single top-level atom. However, there is no requirement to do so.

The data within an atom should be stored in a canonical form on all platforms. It should be always in big-endian format or always in little-endian format. Different types of atoms can be stored in different endian orders but for a single type of atom, it should always use the same order. This allows the settings to be created in the Mac OS and read in Windows or vice-versa.

In either MovieImportSetSettingsFromAtomContainer or MovieExportSetSettingsFromAtomContainer, you should not necessarily expect all atoms to be included in the atom container you receive. This allows another developer, for example, to create a settings atom container, add atoms and data for only those parts of the settings that should be changed, and then pass this incomplete atom container to the component. The component then only changes those particular settings, leaving other settings alone. QuickTime’s own components use this approach.

If nil is passed for the settings to the component routines, return paramErr.

If your component does not have configurable settings, you do not need to implement the settings-related routines.

Registering Movie Data Export Components

QuickTime allows more than one export ('spit') component to be registered for the same type of file and the same export source (the movie or the particular track type). This is accomplished in a way that preserves compatibility with third-party components that may have already been written using the former rules.

EXTERN_API( ComponentResult )

MovieExportGetSourceMediaType (MovieExportComponent  ci, OSType * mediaType);

movieExportMustGetSourceMediaType = 1L << 19,

Export Registration Mechanism

Both the Movie and the DVC export components use the export registration mechanism. The components are registered as shown below.

componentType  'spit'

componentSubType  'MooV'

componentManufacturer  'appl'

componentFlags  canMovieExportFiles  + canMovieExportFromProcedures  +

                hasMovieExportUserInterface   + canMovieExportValidateMovie

                + movieExportMustGetSourceMediaType

componentType 'spit'

componentSubType   'dvc!'

componentManufacturer 'appl'

componentFlags  canMovieExportFiles  + canMovieExportFromProcedures

                + hasMovieExportUserInterface  + canMovieExportValidateMovie

                + movieExportMustGetSourceMediaType

Because the DVC component uses the QuickTime Movie export component, it searches for the 'MooV' exporter, using the following ComponentDescription values:

cd.componentType = 'spit';

cd.componentSubType = MovieFileType;

cd.componentManufacturer = 'appl';

cd.componentFlags = canMovieExportFromProcedures

                    + movieExportMustGetSourceMediaType;

cd.componentFlagsMask = cd.componentFlags;

If you are working with export components (either writing them, or trying to enumerate or otherwise match up components with source media types) you need to understand this registration mechanism.

Implementing Movie Data Export Components

You can implement a movie data export component by calling the MovieExportFromProceduresToDataRef function.

Because many existing applications expect to be able to perform an export operation from a movie or track, export components should support MovieExportToFile, MovieExportFromProceduresToDataRef and MovieExportToDataRef.

Listing 6-5 shows how to implement MovieExportToFile so that it simply calls MovieExportToDataRef.

Listing 6-5  Calling MovieExportToDataRef from MovieExportToFile

pascal ComponentResult MovieExportToFile(Globals store, const FSSpec *theFile, Movie m, Track onlyThisTrack, TimeValue startTime, TimeValue duration) { ComponentResult err;

     AliasHandle alias;

     err = QTNewAlias (theFile, &alias, true);

     err = MovieExportToDataRef(store->self, (Handle)alias, rAliasType, m, onlyThisTrack, startTime,

           duration);

     DisposeHandle((Handle)alias); }

Listing 6-6 shows how to use the utility routines provided by the QuickTime movie data export component to implement MovieExportToDataRef by calling MovieExportFromProceduresToDataRef. Your implementation may differ, depending on the types of data to be exported. For example, the number and type of data sources created may change. This example creates a single sound data source, and is appropriate for any movie data export component that exports audio only.

Listing 6-6  Calling MovieExportFromProceduresToDataRef from MovieExportToDataRef

pascal ComponentResult MovieExportToDataRef(Globals store, Handle dataRef,

  OSType dataRefType, Movie m, Track onlyThisTrack, TimeValue startTime,

  TimeValue duration) {

     ComponentResult err;

     ComponentDescription cd;

     ComponentInstance ci;

     TimeScale scale;

     MovieExportGetPropertyUPP getPropertyProc = nil;

     MovieExportGetDataUPP getDataProc = nil;

     void *refCon;

     long trackID;

     cd.componentType = MovieExportType;

     cd.componentSubType = 'MooV';

     cd.componentManufacturer = 0;

     cd.componentFlags = canMovieExportFromProcedures;

     cd.componentFlagsMask = canMovieExportFromProcedures;

     err = OpenAComponent(FindNextComponent(nil, &cd), &ci);

     err = MovieExportNewGetDataAndPropertiesProcs(ci, SoundMediaType,

           &scale, m, onlyThisTrack,  startTime, duration, &getPropertyProc,

           &getDataProc, &refCon);

     err = MovieExportAddDataSource(store->self, SoundMediaType, scale,

           &trackID, getPropertyProc, getDataProc, refCon);

     err = MovieExportFromProceduresToDataRef(store->self, dataRef, dataRefType);

}

The code in Listing 6-6 retrieves default property and data procedures, instead of providing them, by using the QuickTime Movie export component. It also must dispose of these procedures. They take care of interpreting the tracks and returning media properties and data.