What's New in QuickTime 5

Adding Media Skins Using the QuickTime API

You can also add a media skin to a movie programatically -- for example, to enhance a movie editing application.

You could do this by mimicking the steps just described in the section "Creating Media Skins" . That is, you can generate a movie file, a pair of black-and-white image files, and a small XML text file that points to them, then call a movie importer to put them all together, flatten and save.

But it's simpler to add a media skin to a movie in memory without going through an XML skin importer. The process is as follows:

Locate two black-and-white PICT files, or create two PICT images in RAM, to act as a window region mask and a drag region mask (You can use graphic importer and exporter components to convert a BMP or GIF to a PICT). See Figure 13 and Figure 14 for examples of these kinds of images.
Create a PicHandle that points to each mask image.
Add a new track to the movie.
Add a media of type 'skin' to the new track.
Tell the media handler to put the masks in a public resource.
Flatten and save.

The code snippet shown in Listing 2 provides a general outline of how you can add a media skin programmatically to a QuickTime movie, and is intended primarily as a guide to the process -- not as actual working code.

Listing 3 , however, is working code that walks you through the various steps you need to follow in order to add media skins programmatically to a QuickTime movie.

Listing 2 A general outline of how you add a media skin to a QuickTime movie



 
//Adding a skin without using the importer



// Somehow create a picture handle:



    PicHandle winRgnHndl = nil;

    PicHandle dragRgnHndl = nil;



    winRgnHndl = MyMagicalCode();

    dragRgnHndl = MyMagicalCode();



    // create a new track



    theTrack = NewMovieTrack(myMovie, ((Fixed)movieBox.right) << 

                            ((Fixed)16, movieBox.bottom) << 16, 0);



    // must have someplace for the sample data to go

    // could use BeginMediaEdits, or...

    // create a cool handle that the HandleDataHandler can deal with,

    // so I can add this stuff in ram without needing a file

    dataRef = NewHandleClear(5);

    atomHeader[0] = EndianU32_NtoB(8);

    atomHeader[1] = EndianU32_NtoB('data');

    PtrAndHand(atomHeader, dataRef, 8);



    // add a skin media structure to the movie track

    theMedia = NewTrackMedia(theTrack, 'skin', movieTimeScale, dataRef, 

                             HandleDataHandlerSubType);



    // retrieve media handler reference so we can call it

    mh = GetMediaHandler(theMedia);



    // tell the media handler to add the masks 

        // 'skcr' is skin content region

        // 'skdr' is skin drag region

        // final parameter is length -- set to 0 for an allocated handle

    err = MediaSetPublicInfo(mh, 'skcr', winRgnHndl, 0);

        if (err) goto bail;



    err = MediaSetPublicInfo(mh, 'skdr', dragRgnHndl, 0);

        if (err) goto bail;



    // dispose of the Handle when done

    DisposeHandle(dataRef);

    dataRef = nil

Listing 3 Adding media skins programmatically to a QuickTime movie



 
OSErr QTSkin_AddSkinTrack (Movie theMovie){

        Track myTrack = NULL; // the skin track

        Media myMedia = NULL; // the skin track's media

        Rect myRect;

        MediaHandler myHandler = NULL;

        PicHandle myContentPic = NULL; // window mask

        PicHandle myDragPic = NULL; // drag mask

        OSErr myErr = paramErr;



        if (theMovie == NULL)

            goto bail;

 

// elicit the two pictures we need from the user

        myContentPic = QTSkin_GetPicHandleFromFile();

        if (myContentPic == NULL)

            goto bail;

        myDragPic = QTSkin_GetPicHandleFromFile();

        if (myDragPic == NULL)

            goto bail;



// get the movie's dimensions

        GetMovieBox(theMovie, &myRect);

        MacOffsetRect(&myRect, -myRect.left, -myRect.top);



 
// create the skin track and media

        myTrack = NewMovieTrack(theMovie, FixRatio(myRect.right, 1), 

                                FixRatio(myRect.bottom, 1), kNoVolume);

        if (myTrack == NULL)

            goto bail;



        myMedia = NewTrackMedia(myTrack, FOUR_CHAR_CODE('skin'), 

                                GetMovieTimeScale(theMovie), NULL, 0);

        if (myMedia == NULL)

            goto bail;



 
// find a media handler that understands skins

        myHandler = GetMediaHandler(myMedia);

        if (myHandler == NULL)

            goto bail;



// tell the media handler to add 

// the skin content picture

        myErr = MediaSetPublicInfo(myHandler, FOUR_CHAR_CODE('skcr'),

                                    (void *)myContentPic, 0);

        if (myErr != noErr)

            goto bail;



// now add the skin drag picture

        myErr = MediaSetPublicInfo(myHandler, FOUR_CHAR_CODE('skdr'),

                                    (void *)myDragPic, 0);

        if (myErr != noErr)

            goto bail;

// note: the last parameter passed to 

// MediaSetPublicInfo is the data size;

// pass 0 for an allocated handle



// add the media to the track

        myErr = InsertMediaIntoTrack(myTrack, 0, 0,

                GetMediaDuration(myMedia), fixed1);



// skin tracks should be disabled...

        SetTrackEnabled(myTrack, false);

bail:

    if (myContentPic != NULL)

            KillPicture(myContentPic);

    if (myDragPic != NULL)

            KillPicture(myDragPic);

    return(myErr);

}

What's New in QuickTime 5