Enhancements

• Improved QuickTime Player application User Interface (UI); new audio and video controls, as well as a new scrollable Channel window and Get Movie Properties dialog (among other enhancements). In the Pro (registered) version, there are now ordinary menu items for commands such as “Add Scaled,” that were previously hidden unless you pressed modifier keys, such as Shift, ctrl, alt, or Command.

• The capability to customize the appearance of QuickTime Player by adding a “media skin” to your movie. A media skin specifies the size and shape of the window that the movie is displayed in, while also specifying which part of the window is draggable. A QuickTime movie does not have to be surrounded by a frame. No controls are displayed, except those embedded in the movie using Flash tracks or wired sprites.

• Digital Video (DV) codec optimizations, both compression and decompression, for improved quality and performance on Power Macintosh G3 and Power Mac G4 computers.

• Velocity Engine (AltiVec) and multiprocessor support for DV codecs.

• Inclusion of the QuickTime VR Flattener extension as part of a Full Install of QuickTime, allowing export of VR panoramas in fast-start format with a selectable preview image (or grid), enhanced to support cubic VR as well as cylindrical VR.

• A VR exporter that splits multinode VRs and generates HTML for URL linking, and a VR exporter for object compression.

• Additions to AppleScript, including a new suite of editing features and commands. These features are useful for QuickTime authors who need to automate certain processes, such as batch preparation of QuickTime movies to include copyright information, hypertext links, or full-screen presentation.

• MP3 improvements, including access to ID3v2 metadata.

• Support for new SMIL attributes, such as clip-begin, clip-end, and qt:fullscreen.

• Support for new Travelling Matte effects and gradient wipes, which are useful for application developers working in video and movies.

Changes to the Installer

• Addition of a new Third-party QuickTime Component Downloader. This is designed to provide a registry of QuickTime components on an Apple server from third-party developers who want to include their components in user downloads and updates on an as-needed basis.

• The Installer now recognizes previous installations of QuickTime for Java and will now update them, even during a Full Install.

Support for New Formats

• Support for MPEG 1 playback, both local and streaming on Macintosh and Windows.

• Introduction of a new QuickTime VR cubic playback engine.

• Addition of Flash 4 support.

• Changes and improvements to the QuickTime Music Synthesizer, including support for industry-standard DLS (Downloadable Sound) and Sound Font 2 formats.

Other New Features

• Additions and changes to QuickTime for Java –– including support for a new idling mechanism.

• New EMBED tag parameters and URL extensions.

• New API functions, including a broadcasting API for Mac OS that allows third-party developers to write broadcasting applications or add broadcasting to existing applications.

• Addition of new wired actions and operands.

• A new MIME type (.qtl=application/quicktimeplayer) that allows you to launch movies in QuickTime Player from a text link.

• New XML importer allows you to embed QuickTime URLs in a small text file.

• New ability to render effects and transitions in real time in DV format on Macintosh computers equipped with compatible hardware accelerator cards.

Version Differences

QuickTime 5 is currently available in three versions:

• QuickTime 5.0.1 for Mac OS 8, Mac OS 9, and Windows

• QuickTime 5 for Mac OS X

• QuickTime 5.0 RT for Mac OS 8 and Mac OS 9

QuickTime 5.0.1 is the current release for Mac OS 8, Mac OS 9, and Windows. It replaces QuickTime 5.0 RT, which was distributed only on CD for Macintosh computers. QuickTime 5.0 RT has essentially the same feature set as QuickTime 5.0.1.

QuickTime 5 for Mac OS X does not currently support the following features:

• Media skins

• The complete set of broadcasting APIs

• QuickTime VR authoring components

• Hotpicks movie

• The PictureViewer application (Mac OS X offers the Preview application in its place).

• The complete set of QuickTime Player AppleScript features

QuickTime VR Controls

When QuickTime Player displays a QuickTime VR movie, it provides users with a set of controls to manipulate VR objects and panoramas. A VR panorama lets the user stand in a virtual reality space, such as the church cathedral illustrated in Figure 1-7, and explore immersively the dimensions of a full 360 panorama –– panning across, as well as zooming in and out of the panorama.

In QuickTime 5, authors can create VR panoramas in which users also have the ability to tilt up and down a full 180, so that you can see the ceiling of the cathedral as well as the floor in Figure 1-7. The actual horizontal and vertical range is determined by the panorama itself. To look left, right, up and down, you drag with the mouse across the panorama.

In addition to navigating a QuickTime VR movie by holding the mouse button down and dragging inside the panorama, the user can manipulate the panorama by clicking various buttons:

• A go-back button. This allows the user to return to the previous node (a single viewpoint in a panorama). Clicking this button restores the previous static pan angle, tilt angle, and field of view. The button is enabled only for multinode (multiple viewpoint) panoramas.

• A zoom-out button. This allows the user to zoom out. Holding down the mouse button while the cursor is over this control causes the field of view of the displayed node to increase, thereby making the object or panorama appear to move away from the viewer.

• A zoom-in button. This allows the user to zoom in. Holding down the mouse button while the cursor is over this control causes the field of view of the displayed node to decrease, thereby making the object or panorama appear to move toward the viewer.

• A hot spot display button. This allows the user to highlight the visible hot spots. A single click toggles hot spots on; another click toggles hot spots off. This is a change in behavior from previous hotspot buttons, which displayed hotspots only while the mouse button was held down.

In addition to these buttons, there is also a label display area (not shown in Figure 1-7) in which helpful information can be displayed. For instance, when the cursor is over one of the buttons, the button’s name appears in the label display area. Similarly, when the cursor is over a hot spot, the hot spot’s name (if it has one) appears in the label display area.

New Player Application Capabilities

In addition to the user interface changes, QuickTime 5 introduces new capabilities to the QuickTime Player application. These are described as follows:

• If a complete installation is performed, QuickTime now includes the VR Flattener component. If a VR panorama is loaded in QuickTime Player, and the VR Flattener component is installed, the Export pop-up menu includes an item named Movie to Fast Start QuickTime VR Movie. Choose this item to export the panorama as a Fast Start VR movie with a preview. There will also be an item named either “Movie to QuickTime VR Movie 1.x” or “Movie to QuickTime VR Movie 2.x,” allowing you to convert your panorama from one format to the other.

• In addition to exposing many more of QuickTime Player’s features to AppleScript in QuickTime 5 (see AppleScript Changes and Additions for more information), the features of the Plugin Helper application are now accessible through AppleScript extensions to QuickTime Player. You still need to use Plugin Helper to set plugin attributes manually, but you can use AppleScript and QuickTime Player to automate the task.

• It is now possible to attach a “media skin” to a movie, which controls the appearance and behavior of the QuickTime Player 5 application when the movie is played. A media skin allows you to control the size and shape of the Player window, as well as the color, width, and texture of the frame (if any). It also eliminates the visible movie controller or VR controller, allowing you to design your own controls using wired sprites. This is discussed in more detail in the next section, Media Skins.

Creating Media Skins

A media skin can be added to a movie using a text editor, a graphics program such as Adobe Photoshop, and QuickTime Player (Pro version).

In a typical case, you might want to replace QuickTime Player’s brushed-metal frame with one of your own design, as shown in Figure 1-10. Here are the steps that you would follow:

1. Create an image of your new frame using a graphics program, or perhaps scan in a photo of an actual device.

1. Open this image in QuickTime Player and add it to an existing movie as a background image, as shown in Figure 1-11.

1. You would also typically create your own movie controls, using Flash or wired sprites (and a wired sprite editor such as LiveStage Pro or Adobe’s GoLive), and add these as a Flash track or sprite track on top of your frame image, as shown in Figure 1-12. Call this Framed.mov.

1. Create a mask image the size and shape of your frame (Figure 1-13). This image defines the window created when your movie plays. The image should be black where you want your window, and white elsewhere. The image can be a BMP, GIF, PICT, or any other format that QuickTime understands. Call this WinMask.pct.

1. Create a second mask image the size and shape of the draggable part of your frame (Figure 1-14). Typically, this would be the same as your first mask, with white areas where your text, video, and controls will appear. Again, this should be saved as a black-and-white image in a format that QuickTime can display. Call this DragMask.pct.

1. Using a text editor, create a small file with the following syntax:

   <?xml version="1.0"?>

   <?quicktime type="application/x-qtskin"?>

   <skin>

   <movie src="Framed.mov"/>

   <contentregion src="WinMask.pct"/>

   <dragregion src="DragMask.pct"/>

   </skin>

2. Save as plain text, with the .mov file extension. Call this SkinXML.mov.

3. Open SkinXML.mov using QuickTime Player. Save as a self-contained movie. Call this Finished.mov.

You can now put Finished.mov on a CD, email it to a friend, or embed a link to it in a Web page. You can target the link to open your movie in QuickTime Player using the EMBED tag. For example:

<EMBED SRC="poster.qtif" TYPE="image/x-quicktime" HEIGHT=120 WIDTH=160  HREF="Finished.mov" TARGET="quicktimeplayer" >

This tag would embed a QuickTime image file named poster.qtif in a Web page. If the viewer clicks the image, QuickTime will launch Finished.mov in the QuickTime Player application.

To launch Finished.mov automatically, without the viewer clicking anything, you add AUTOHREF="true" to the EMBED tag.

The example just given uses a static image as a custom frame, but remember: a media skin just provides masks to use when displaying your movie. Any visual media type can show through the masks, including motion video and special effects, such as those possible with the QuickTime cloud or fire effects.

Any part of your movie can be made into a draggable region. However, tracks that respond to mouse events, such as VR panorama tracks or wired sprite tracks, should not be covered by a drag mask — the drag behavior prevents mouse events from reaching underlying tracks.

Current Limitations

Currently, a movie can have only one skin track. You cannot dynamically enable or disable skin tracks. The skin track’s masks are stored in the movie file as 1-bit pixel depth PICTs and cannot be changed dynamically.

Note that skins are not available in the current release of Mac OS X.

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:

1. 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 1-13 and Figure 1-14 for examples of these kinds of images.

2. Create a PicHandle that points to each mask image.

3. Add a new track to the movie.

4. Add a media of type 'skin' to the new track.

5. Tell the media handler to put the masks in a public resource.

6. Flatten and save.

The code snippet shown in Listing 1-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 1-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 1-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 1-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);

}

Adding Custom Media Skins with AppleScript

QuickTime 5 provides additional AppleScript support in the QuickTime Player application, which is discussed in the section AppleScript Changes and Additions. The QuickTime Player scripting dictionary, for example, contains new commands and properties that can be used to automate many movie-editing and playback tasks.

This section describes how you can create an AppleScript droplet with a custom media skin (the code for this droplet is already supplied). Droplets are special AppleScript applications that respond to files and folders dragged onto their icon. Each droplet has properties and parameters that can be set by double-clicking the droplet and clicking the “Set Prefs” button in the main dialog.

In this example, the droplet automates the process of creating a QuickTime movie with a media skin.

Refer to <http://www.apple.com/applescript/qtas5/qtas5p2.htm> for a collection of example scripts that are available in QuickTime 5.

Media Skin Droplet

The script of the media skin droplet assembles the components of a media skin movie and saves the results as a self-contained QuickTime movie file. This section describes how the script works and the steps required to use the example files included with the script. Note that this script only processes standard QuickTime movie files of file type “MooV”.

Creating the Media Skin Image Files

To create a custom media skin for your movies, you need to create three specific image files:

• The media skin. This image (Figure 1-15) will be the window in which the movie is played. It can be of nearly any shape or size.

In the example included with this script, there is a simple media skin file that adds a standard border and title bar to the movie. This image is designed to display a movie having a width of 240 pixels and a height of 180 pixels. The blue region defines the area to display the video content of the movie.

Note that the offset of the top left of the blue region is 6 pixels horizontally and 22 pixels vertically from the top left of the media skin image. The script uses these measurements in order to place the video track in the corrext position over the media skin background. Note also that the size and offset info has been overlaid on the media skin image.

• The drag mask image. This image (Figure 1-16) defines the areas of the window that can be clicked by the user to drag the window. The black regions of the image will be the clickable areas of the finished window. In this example, the title bar and sides of the movie will be the drag regions.

• The window mask image. This image (Figure 1-17) defines the visible area of the media skin window. Black regions will be visible to the user, white areas will be invisible. In this example, the entire area defined by the media skin image will be visible.

Transparent Overlay Media Skins

If you want the media skin to partially cover the source video, you need to fill the area to be transparent with a solid color of a specific RGB value, such as White, Black, %50 Gray, or 100% Blue.

In the following example image (Figure 1-18), the QuickTime Q has been filled with %50 Gray. The script preferences can be set to adjust the track’s operation color and transfer mode for this value, and the center of the Q image will become transparent when the skinned movie is created.

Setting the Script Preferences

The script droplet relies on preferences, set by the user, to locate and manipulate the essential files. This particular script is designed to look for the various image files in the same folder as the droplet. If the essential image files are not in the same folder as the script, the script will not execute.

You can make copies of this droplet to be placed in other folders containing your various media skin files. You set the preferences for each droplet to work with its neighbor files.

To set the preferences for the droplet, you double-click its icon in the Finder to summon the status dialog (Figure 1-19). The dialog shows the current settings for the various script preferences. Click the “Set Prefs” button to set each of the script preferences.

The first three preferences are for identifying the image files to be used by the script when constructing the media skin movie.

In the first dialog (Figure 1-20), enter the name of the image file which will be used as the media skin background. You may either enter the name in the input field or click the “Choose File” button to locate the appropriate file. The script will then place the name of the chosen file in the input field for you.

After you have entered the name of the appropriate media skin image file (Figure 1-21), click the “OK” button to proceed.

You repeat this process in the forthcoming dialogs for identifying the window mask image and the drag mask image.

After inputting the names of the other files, two successive dialogs appear, asking you to enter the offset to be used to position the video track against the chosen media skin background. These measurements depend on the design of your media skin.

In the first dialog (Figure 1-22), you enter the horizontal offset (in pixels) from the left of the media skin image to the left of the video display area.

In the second dialog (Figure 1-23), you enter enter the vertical offset (in pixels) from the top of the media skin image to the top of the video display area.

The next dialog (Figure 1-24) determines if you want the media skin image to be placed behind the source video or in front of the source video. Media skin images placed over the source video must have areas of a solid color that will be made transparent during the creation of the skinned movie.

If you clicked the “Yes” button, a list dialog (Figure 1-25) appears from which you can choose the color which the script will make transparent. If your overlay color is not in the list, you may enter its RGB values individually by clicking the “Other” button at the bottom of the list dialog.

If you clicked the “Other” button, a series of three dialogs will prompt you for each of the RGB values for the color to be made transparent. Each color is specified as a list of individual Red, Green, and Blue values: {Red value, Green value, Blue value}. Each individual RGB color component is an integer between 0 and 65535, with 0 being the minimum and 65535 being the maximun value.

For example, White is {65535, 65535, 65535}, Black is {0, 0, 0}, 100% Red is {65535, 0, 0}, 50% Gray is {32768, 32768, 32768}, etc. Note that the values you enter in these dialogs must exactly match those of the area in the overlay image that is meant to be transparent.

The final two preference dialogs are for setting the playback properties.

Click the “Yes” button if you want the movie to automatically start playing when opened.

Click the “Yes” button if you want the movie to automatically close when it has finished playing.

After setting the property, the script will return to the status dialog (Figure 1-29). Click the “Done” button to exit the script.

If the media skin image is set to overlay, the operation color name or value will be displayed in the status dialog (Figure 1-30).

Running the Script

To use the script, you drag a movie file, or multiple files, or folders of movie files onto the droplet. A dialog (Figure 1-31) appears prompting you for the destination folder for the finished files.

Once chosen, a media skin copy of each dragged-on movie is created and placed into this folder.

Completed Examples

Figure 1-32 (top) shows a completed example of a basic 240 x 180 skinned QuickTime movie, with standard border and title. In this case, the airplane is shown flying diagonally from the lower portion of the screen to the upper. Figure 1-32 (bottom) shows a completed example of a 144 x 108 overlaid skinned Q with the airplane flying inside the Q.

High-Quality Decompression

Both scalar and vector codec quality has been improved significantly in this release. There are performance improvements as well. The code is optimized in both scalar and vector codecs to pack pixels directly to the output format, which provides a significant improvement in performance for r408.

QuickTime 5 supports optimized single field decompression, which improves performance for cases when the single field hint (hintsSingleField) is set. The vector codec now includes gamma correction when decompressing to the screen.

Improved Compression Quality and Performance

Overall, there is a significant improvement in both compression quality and performance. Special attention has been paid to make sure that existing DV content can be recompressed with few additional artifacts.

Improved Low-Quality Vector Decode

The quality of low-quality decode on vector machines (400 MHz or greater) has been improved, while also improving performance.

Addition of Multiprocessor Support

Multiprocessor support has been enabled for vector decode (i.e., high quality, low quality, playback and scrub/render). Multiprocessor support has also been enabled for encode in the vector case. For the actual DV operation, the results are nearly two times faster on a two CPU computer than the same code running in non-multiprocessor mode.

Overview

QuickTime 5 has defined new APIs to retrieve the video and sound latencies from Video Codecs and Sound Output Components.

The latency values are used to separately offset the timebases of the video and/or sound media from that of the movie timebase. The offsets are based on pipeline delays within the implementation of the sound or video components. For example, given some video hardware that has several stages that will take five frames to go through between the start of decompression and when the data is displayed, the video codec should report a latency of five frames, so that QuickTime will schedule the frames in advance. The codec is responsible for reporting a latency that represents its accurate pipeline in order to maintain audio and video synchronization.

Usage

Video Codec Latency API

The following API is used by QuickTime to retrieve the video latency:

ImageCodecGetDecompressLatency

Retrieves the video latency from the specified video codec.

pascal ComponentResult ImageCodecGetDecompressLatency(ComponentInstance                                              ci, TimeRecord * latency);

pascal ComponentResult myCodecGetDecompressLatency(myCodecGlobals *glob,

                                                    TimeRecord *latency)

{

    OSErr   result = paramErr;

    // Example setting 33 ms latency

    if (latency != nil) {

        latency->value.hi = 0;

        latency->value.lo = 33;             // latency value

        latency->scale = 1000;              // 1 ms scale

        latency->base = nil;

        result = noErr;

    }

    return result;

}

Sound Output Latency API

Retrieves the audio latency from the specified sound output component.

The new selector siOutputLatency for the SoundComponentGetInfo function is used by QuickTime to retrieve the sound latency. (The infoPtr parameter points to a time record.)

#define siOutputLatency ‘olte’

The following code snippet shows an example implementation of this selector:

static pascal ComponentResult mySoundGetInfo(SoundComponentGlobalsPtr globals,  SoundSource sourceID, OSType selector, void *infoPtr)

{

    ComponentResult             result = noErr;

    PrefStructPtr               prefsPtr;

    prefsPtr = *(globals->prefsHandle);

    switch (selector) {

case siSampleSize:              // return current sample size

            *((short *) infoPtr) = (short)prefsPtr->sampleSize;

            break;

case siOutputLatency:                                               // return  the sound output latency

        // in this example, 25 ms

if (infoPtr != nil) {

                infoPtr->value.hi = 0;

                infoPtr->value.lo = 25;             // sound latency

                infoPtr->scale = 1000;              // 1 ms scale

                infoPtr->base = nil;

            }

            break;

. . .

}

Enabling Asynchronous MP Decompression Using the Base Decompressor

The Base Decompressor, which has been available since QuickTime 3.0, is designed to simplify the job of writing an Image Decompressor. It deals with the job of managing asynchronous scheduled decompression, manages the queue safely, and avoids synchronization issues.

In QuickTime 5, the Base Decompressor has been extended to simplify making an image decompressor component able to perform asynchronous decompression in a single MP task. The JPEG, H.263, Cinepak, and Video decompressors use this mechanism to run asynchronously. The H.263 compressor has been similarly modified to run asynchronously.

If you have a decompressor that uses the base codec, all you need to do to support the asynchronous MP mode is to implement the ImageCodecGetMPWorkFunction function.

Your implementation should call your base decompressor instance’s ImageCodecGetBaseMPWorkFunction function, and pass to it a UPP for your DrawBand function:

pascal ComponentResult

ExampleCDGetMPWorkFunction(

                ExampleSubDecompressorGlobals *storage,

                ComponentMPWorkFunctionUPP *workFunction, void **refCon)

{

    if( 0 == storage->drawBandUPP )

        storage->drawBandUPP =

                        NewImageCodecMPDrawBandUPP( ExampleCDDrawBand);

    return ImageCodecGetBaseMPWorkFunction(storage->delegateComponent,

                                        workFunction, refCon,

                                        storage->drawBandUPP, storage);

}

If you implement the ImageCodecGetMPWorkFunction selector, your DrawBand function must be MP-safe. (MP safety is an even stricter condition than interrupt safety. As well as not calling routines that may move or purge memory, you may not make any calls which might cause 68K code to be executed. Ideally, your DrawBand function should not make any API calls whatsoever.)

Taking Advantage of Asynchronous MP Codecs in Your Application

QuickTime will automatically call a codec asynchronously when you’re playing a movie. If your application calls the Image Compression Manager directly to perform compression or decompression operations, you can pass a completion routine to CompressSequenceFrame or DecompressSequenceFrame/S/When to enable asynchronous operation. (If the codec does not support asynchronous operation, the API will run synchronously but call your completion routine before returning.)

If your application calls the Standard Compression component to perform image compression, you’ll need to call a new API variant, SCCompressSequenceFrameAsync, which is new with QuickTime 5 and supports completion routines. While this is running, you should occasionally call SCAsyncIdle from system task time.

Note that the H.263 compressor has been modified to run asynchronously if requested.

SCCompressSequenceFrame

This function compresses a single frame in a sequence-compression operation. You must call this function once for each frame in the sequence, including the first frame.

This function is available in previous versions of QuickTime.

pascal ComponentResult SCCompressSequenceFrame (ComponentInstance ci,
   PixMapHandle src,
   const Rect *srcRect,
   Handle *data,
   long *dataSize, short
   *notSyncFlag);

SCCompressSequenceFrameAsync

This is an asynchronous variant of SCCompressSequenceFrame which accepts a completion routine.

SCCompressSequenceFrameAsync (ComponentInstance ci,
   PixMapHandle src,
   const Rect * srcRect, Handle
   * data, long * dataSize, short
   * notSyncFlag,
   ICMCompletionProcRecordPtr
   asyncCompletionProc);

SCAsyncIdle

SCAsyncIdle (ComponentInstance ci);

The QTVR Flattener

The QTVR Flattener is a movie export component that converts an existing QuickTime VR single node movie into a new movie that is optimized for the Web. The flattener re-orders media samples; and for panoramas the flattener creates a small preview of the panorama. When viewed on the Web, this preview appears after 5% to 10% of the movie data has been downloaded, allowing users to see a lower-resolution version of the panorama before the full resolution version is available.

In QuickTime 5, this QTVR Flattener has been enhanced. There is a new implementation of tile ranking that works with horizontal and cubic panos, and also with two-dimensional tiling. The result is that panoramas appear to come in faster.

To use the QTVR Flattener from your application, you first create a QuickTime VR movie, then open the QTVR Flattener component and call the MovieExportToFile routine, as shown in Listing 1-4.

Listing 1-4  Using the QTVR flattener

ComponentDescription desc;

Component flattener;

ComponentInstance qtvrExport = nil;

desc.componentType = MovieExportType;

desc.componentSubType = MovieFileType;

desc.componentManufacturer = kQTVRFlattenerManufacturer;

desc.componentFlags = 0;

desc.componentFlagsMask = 0;

flattener = FindNextComponent(nil, &desc);

if (flattener) qtvrExport = OpenComponent (flattener);

if (qtvrExport)

    MovieExportToFile (qtvrExport, &myFileSpec, myQTVRMovie, nil, 0, 0);

The code snippet shown in Listing 1-4 creates a flattened movie file specified by the myFileSpec parameter. If your QuickTime VR movie is a panorama, the flattened movie file includes a quarter size, blurred JPEG, compressed preview of the panorama image.

err = MovieExportDoUserDialog (qtvrExport, myQTVRMovie, nil, 0,                                  0, &cancel);

Boolean yes = true;

QTAtomContainer exportData;

QTAtom parent;

err = QTNewAtomContainer(&exportData);

// create a parent for the other settings atoms

err = QTInsertChild (exportData, kParentAtomIsContainer,

            kQTVRFlattenerSettingsParentAtomType, 1, 0, 0, nil, &parent);

// Add child atom to indicate we want to import the preview from a file

err = QTInsertChild (exportData, parent,

                    kQTVRFlattenerCreatePreviewAtomType, 1, 0,

                    sizeof (yes), &yes, nil);

// Add child atom to tell which file to import

err = QTInsertChild (exportData, parent,

            kQTVRFlattenerImportPreviewAtomType, 1, 0,

            sizeof (previewSpec), &previewSpec, nil);

// Tell the export component

MovieExportSetSettingsFromAtomContainer (qtvrExport, exportData);

ComponentInstance sc;

QTAtomContainer compressorData;

SCSpatialSettings ss;

sc =    OpenDefaultComponent(StandardCompressionType,StandardCompressionSubType);

ss.codecType = kCinepakCodecType;

ss.codec = nil;

ss.depth = 0;

ss.spatialQuality = codecHighQuality

err = SCSetInfo(sc, scSpatialSettingsType, &ss);

err = SCGetSettingsAsAtomContainer(sc, &compressorData);

MovieExportSetSettingsFromAtomContainer (qtvrExport, compressorData);

The QTVR Multinode Splitter

The QTVR Splitter, a movie export component, takes a QTVR version 2.x multinode movie and exports a set of single-node movies with relative URL links to each other.

The QTVR Splitter works by changing all of the link hotspots to URL hotspots, leaving any previously defined URL or undefined (blob) hotspots unchanged. If the QTVR Flattener component is present, the Splitter gives you the option of using it to add fast-start data to the movies, including previews for panorama nodes. Additionally, the Splitter will generate a text file with HTML embed tags for each movie created.

When you display the movies’ output by the Splitter using the QuickTime Plugin, clicking the relative URL links opens the other nodes in the browser window. When loaded in a frame, the Plugin loads the new movies in the same frame.

When the user clicks a link which displays a multinode movie split this way, the first thing to download is the hotspot track, which is live immediately. Then any preview data is downloaded, and finally the tiles download in and are placed over the background grid or preview. The user can jump to another node at any time, and only the nodes they visit are downloaded, unlike a multinode movie, which does not allow navigation until the entire file has downloaded, and therefore downloads all of the nodes, whether the user visits them or not.

<A href src="my_scene_node127.mov">click to view the QTVR scene"</a>

<Embed src="my_scene_node127.mov"...

<frameset>...

QuickTime VR Object Movie Compressor

The QuickTime VR Object Movie Compressor, a movie export component, takes a multirow object movie and compresses frames in multidimensions with the goal of making the file smaller. It includes the user settings dialog box shown in Figure 1-36.

The user settings for the QuickTime VR Object Movie Compressor include:

• The Standard Compression Setting, which is set by clicking on the Compression Setting button.

• The target file size of the compressed VR object movie, which is specified as:

  kQTVRObjExporterSettingsTargetSize = FOUR_CHAR_CODE('tsiz')

• The Block Size Setting, which can also be set from a QT atom container, controls the dimensions of the compression:

  long: blockSize

  type: ‘bsiz’

  Valid Value: 1, 2, 3, 4 which correspond to the block size of

  1x1, 3x3, 5x5, 7x7

General Submission Requirements for Third-Party Components

If you wish to include your component in the third-party component download mechanism, you need to follow certain guidelines and requirements. These include

1. An End User license agreement for your component (in the target language). The agreement should be in plain ASCII text (no formatting), and will be displayed in a scrollable dialog before installing your component. Line wrapping will be done by the dialog, so hard carriage returns should be used sparingly. There will be two buttons (“Agree”, “Disagree”) in the license dialog. You can specify what verbs you want in these buttons. If you do not specify, Apple will use appropriate verbs taken directly from your license agreement.

2. A Macintosh (OS 8/9) QuickTime Component File. This component file should have Macintosh file type of 'thng' and will be installed in the QuickTime Extensions folder in the Macintosh System’s Extension folder.

3. A Macintosh (OS X) QuickTime Component File. This component file (CFM or Mach-O format) should have a .qtx file name extension and will be installed in the /Library/QuickTime folder. It should be a traditional (not bundle-packaged) component file.

4. A Windows QuickTime Component File. This component file should have a .qtx file name extension and will be installed in the QuickTime folder inside the Windows System folder (“System32\QuickTime” for Windows NT/2000, “System\QuickTime” for Windows 95/98/Millenium).

5. Tests. You must provide Apple with test content files and a test procedure that verifies your component has been installed and works correctly. Apple will continue to use these tests as new versions of QuickTime are shipped, so a reasonably thorough set of test content will help ensure that your component continues to work in the future.

There is additional information that you may need to submit:

1. In the QuickTime Updater, your component will be listed as a selectable item in the “Custom” dialog. You can specify the component name you would like displayed there. You can also specify a short description of your component that will be displayed in the Item Description text box, if the user selects your component name in the list. If you do not specify this information, Apple will use your file name (minus the .qtx extension) as the displayed component name, and make up a short description something like “This component adds support for Your_Name_Here to QuickTime”. In either case, Apple will add an approximate download size to the description.

2. If your component is a Movie Importer or Graphics Importer, you should have a 'mime' resource in your component file that describes the file types, file extensions, and MIME types that your importer can handle.

This helps Apple download your component automatically when a Web page with your content is viewed through QuickTime’s browser plug-in.

How and Where Your Component Gets Installed

There are two types of component executables on Mac OS X: Code Fragment Manager (CFM) and Mach-O. You can also build a CFM component updated for Carbon that runs on both Mac OS X and Mac OS 9.

Third-party components are typically stored in the /Library/QuickTime directory, formerly known as the QuickTime Extensions folder. Programmatically, you find this folder by calling FindFolder with the constant kQuickTimeExtensionsFolderType.

Both types of executables –– CFM and Mach-O –– can be packaged in either one of two ways.

1. The “monolithic” way, i.e., where you have a single file that has a resource fork and a data fork. The data fork will contain the code and the resource fork will contain the 'thng' resource and any other resources that are required. In the case of CFM, they would also contain the 'cfrg' resource. The binary could be a CFM executable or a Mach-O executable. Executables that are packaged this way in the /Library/QuickTime directory tend to have their file names ending in .qtx in order to identify them.

2. The other way of packaging components is by means of bundle (directory) packaging, which is typically used by plug-ins and applications. (For more information about bundles, refer to Inside Mac OS X: System Overview, Chapter 4, “Bundles,” which is available for download at http://developer.apple.com/documentation/MacOSX/Conceptual/SystemOverview/index.html.)

As far as components are concerned, there are two important differences between the regular plug-in bundle and the component as a bundle. These have to do with the bundles’ package info file –– PkgInfo –– which is an 8 byte file that’s effectively a type and creator for the bundle, with the first 4 bytes being the type and the second 4 bytes being the creator. For example, Apple’s components all have 'thngapp1' in that file. Similarly, in the Info.plist file within the bundle that’s an XML property list, there is a key in the Info.plist file called CFBundlePackageType. It should have the value 'thng' to identify this as a component.

Localized and Non-Localized Resources

Given that within a bundle the resources are stored in data fork resource files separately from the executable, they can be further split between localizable and non-localizable resources. The 'thng' resources are stored in the non-localized resource file.

In the case of a CFM executable, 'cfrg' resources would also be in that file. Using it in a bundled package, you can use the CF bundle APIs to gain access to pieces of this bundle programmatically, without having to know the organization of a bundle. You can get at resource files –– the Info.plist itself –– and actually store things in the property list for use by your component.

The names of these bundled packages can be:

• example.qtx/

• example.component/

• example.bundle/

The Component Manager will scan a directory looking for names of these bundled packages.

Of the possible name choices available, Apple recommends that you name your component with a .qtx extension. This is preferred because it identifies the component as a QuickTime component.

Recommended Procedures

There are several recommended procedures that you ought to follow. In the case of a Mach-O bundle, you should only export the component entry points. In fact, they must be exported. You should link with a -bundle linker option to help control the name space.

When you are building a Mach-O executable, the 'thng' resource must specify the platform type as 5 and the code resource type as 'dlle'. Thus, you need to have an associated 'dlle' resource containing the component’s entry point name.

The other recommendation is that similar to other dynamically loaded pieces of code, your component files should not contain global variables.

Additional Commands

The following AppleScript commands are new to QuickTime 5, and are accessible through clipboard or Edit menu operations:

• add reference -- movie

  • [scaled boolean] -- should added content be scaled to the duration of current selection?

• clear reference -- movie

• copy reference -- movie

• cut reference -- movie

• make (for creating an empty movie only)

• open image sequence reference -- image file representing beginning of image sequence

  • [frames per second small real] -- the number of frames desired per second

  • [seconds per frame small real] -- the duration of each frame in seconds

• paste reference -- movie

• redo reference -- movie

• trim reference -- movie

• undo reference -- movie

The standard AppleScript command:

• delete reference -- movie (for favorites and tracks only)

Application Class Changes

Additional application element:

• display by numeric index

Updated application property:

• QuickTime connection speed 14.4 Modem/28.8/33.6 Modem/56K Modem/ ISDN/112K Dual ISDN/256 Kbps/384 Kbps/512 Kbps/768 Kbps/1 Mbps/T1/Intranet/LAN [r/o] -- the current connection speed (set in the QuickTime Control Panel)

Additional application properties:

• ignore auto play boolean -- ignore requests to auto-play movies upon opening?

• ignore auto present boolean -- ignore requests to auto-present movies upon opening?

Favorite Class Changes

Addition of two elements:

• file by numeric index

• internet location by numeric index

Movie Class Changes

Additional movie properties.

Note that the following are runtime-only properties, taking effect immediately when you set them:

• close when done

• quit when done

Some of the following are auto properties (persistent), i.e., they are saved with the movie. If you set them, they don’t take effect until the next time you open the movie.

• auto close when done boolean -- will the movie automatically close when done playing? (saved with movie)

• auto play boolean -- will the movie automatically start playing? (saved with movie)

• auto present boolean -- will the movie automatically start presenting? (saved with movie)

• auto quit when done boolean -- will the player automatically quit when done playing? (saved with movie)

• close when done boolean -- close when done playing? (not saved with movie)

• quit when done boolean -- quit the application when this movie is done playing? (not saved with movie)

• controller type standard/qtvr/none -- the type of controller associated with the movie

• live stream boolean [r/o] -- is this a live streaming movie?

• stored stream boolean [r/o] -- is this a stored streaming movie?

• local playback boolean [r/o] -- is this a local movie?

• fast start boolean [r/o] -- is this a fast-start movie?

• max time loaded integer [r/o] -- the amount of time loaded in a fast start movie

• preferred rate small real -- the preferred rate of the movie

• presentation size half/normal/double/screen/current -- size at which the movie will be presented

• presentation mode normal/slide show -- mode in which the movie will be presented

• preview 'csel' -- start time and end time of the movie preview

• href international text [r/o] -- the internet location to open when clicking on the movie (overrides track hrefs)

• plugin settings list [r/o] -- the QuickTime Plugin settings stored in the movie

• saveable boolean -- can the movie be saved?

• load state integer [r/o] -- the current state of a fast-start or streaming movie

• streaming status code small integer [r/o] -- the streaming status code of the movie

• streaming status message international text [r/o] -- the streaming status message of the movie

Track Class Changes

Additional track element:

• annotation by numeric index, by name, by ID

• frame by numeric index

Additional properties.

The following is useful with any track:

• data format international text [r/o] -- the data format

The following are useful with video tracks:

• transfer mode dither copy/no dither copy/blend/transparent/straight alpha/premul white alpha/premul black alpha/straight alpha blend/composition -- the transfer mode of the track

• transfer mode RGB color -- the operation color of the track. Note that not all transfer modes use this value.

• high quality boolean -- is the track high quality?

• single field boolean -- is the visual track single field?

• preload boolean -- should the track be preloaded?

• never purge boolean -- never purge the track?

• data rate integer [r/o] -- the data rate (bytes/sec) of the track

• video depth small integer [r/o] -- the color depth of the video

• is video gray scale boolean [r/o] -- is the video gray scale?

• href international text [r/o] -- the internet location to open when clicking on the track

• chapterlist track -- text track to use as chapter list for this track

• contents type class -- the contents of the track. This is useful for getting or setting chapter track contents all at once. For example: set contents of chapter_track to {"Chapter 1", "Chapter 2", "Chapter 3"}

The following are useful with audio tracks:

• audio sample rate small real [r/o] -- the sample rate of the audio in kHz

• audio channel count small integer [r/o] -- the number of channels in the audio

• audio sample size small integer [r/o] -- the size of uncompressed audio samples in bits

• is audio variable rate boolean [r/o] -- is audio variable bitrate?

The following are useful with streaming tracks:

• streaming bit rate small real [r/o] -- bit rate in bits/second for all streams in track

• streaming quality small real [r/o] -- percent of packets received for all streams in track

Additional Classes

Some Chapter class properties are now modifiable.

    tell text frame 1

        set background color to {2345, 34563, 324}

        set foreground color to {0, 0, 0}

        set justification to left

        set default font to "times"

        set default font size to 18

        set default font styles to {bold, italic}

    end tell

Export Event Changes

Export events have new options. Both "can export" and "export" take a "considering only" property, which restricts the kind of exporter used. The "export" event now takes a "replacing" parameter, which indicates that any existing destination file be deleted before the export is performed.

• can export: Determine if a movie or track can be exported to the desired type

  • can export reference -- the movie or track to export as AVI/BMP/DV stream/FLC/hinted movie/image sequence/picture/QuickTime movie/AIFF/System 7 sound/wave/MuLaw/standard MIDI/text file -- the desired file type

  • [considering only video/sound/text/base/streaming/MPEG/MPEG Audio/MPEG Video/music/timecode/sprite/Flash/tween/3D/QuickTime VR/VR panorama/VR object] -- considering only data of this type within the movie

  Result: boolean -- is the export supported

• export: Export a movie or track to a file

  export reference -- the movie or track to export

  to alias -- the destination file as AVI/BMP/DV stream/FLC/hinted movie/image sequence/picture/QuickTime movie/AIFF/System 7 sound/wave/MuLaw/standard MIDI/text file -- the desired file type

  [using default settings/most recent settings] -- the export

• settings to use

  [using settings preset string] -- the name of the export settings

• preset to use

  [considering only video/sound/text/base/streaming/MPEG/MPEG Audio/MPEG Video/music/timecode/sprite/Flash/tween/3D/QuickTime VR/VRpanorama/VR object] -- considering only media of this type within the movie

  • [replacing boolean] -- should the original file be deleted first?

Other Changes

Application favorite elements can now be created:

• make favorite with data "rtsp://video.hil.no/rtv/videoklipp_ISDN_S.mov"

• make favorite with data alias "Mac OS 9:Media BU:1984.mov"

Movie track elements can now be created to ease chapter track creation:

• make new track at first movie with data {"Chapter 1", "Chapter 2", "Chapter 3"}

• make new track at first movie with data alias "Media:ChapterTrack.txt"

New Wired Actions and Operands

These new wired actions and new operand let you target a Flash track and access data in a Flash track from wired actions. For more information on other new wired actions and operands in QuickTime 5, refer to the section Wired Actions.

Improved QuickTime Music Synthesizer

The QuickTime Music Synthesizer, whose performance and quality of synthesis rendering has been enhanced in QuickTime 5, will support the following new formats:

• Downloadable Sounds (DLS), an industry standard which is used by MPEG-4.

• Sound Font 2 (SF2).

DLS is a sample bank format that describes to the QuickTime Music Synthesizer that you have a particular sample that responds to a particular instrument number that should be used for a range of keys and for a range of velocities, and describes the envelope characteristics of attack, decay, sustain, and release.

For developers, the API for the new QuickTime Music Synthesizer engine is unchanged from the existing API. The note allocator component is still used to access the synthesizer.

New Reverb to Improve Sound Quality

Along with a new synthesis engine, QuickTime 5 provides a new reverb algorithm that improves the quality of the sounds.

The polyphony available to the QuickTime Music Synthesizer is dependent on the type of computer it runs on. The CPU power of the computer is going to determine how much work the synthesizer can get done and that, in turn, will determine the polyphony.

Updated Music Control Panel

The Music control panel has been updated to automatically scan the QuickTime Extensions directory for either Sound Font 2 or DLS files. These appear in the list of “synthesizers” available to QuickTime, and the user can choose one of these sounds banks as the default bank to use to play back QuickTime Music content, if a specific sound has not been assigned in the movie.

Bear in mind that many QTMA movies assume a GeneralMIDI-compliant synthesizer, so generally a user should ensure that the default sample set is a GM-compliant sample set.

Other Improvements

There are a number of improvements to QTMA in this release. These include

• Export to AIFF now respects mono/stereo, bit depth, and sampling rate options, whereas previously these were ignored.

• Synth initialization has been much improved (custom sub-allocator).

• Playback of music movies should start soon after the user clicks Play.

• Improved Sound Font support, so that more files are now parsed correctly.

• MIDI Channel information is typically lost when importing and exporting MIDI files. This has been a longstanding issue with QTMA. This has now been addressed in this release.

Some Limitations of Sound Font 2 and DLS Files

Developers have been asking: How does QuickTime deal with large SF2 files? Does it load samples dynamically as they are needed by a MIDI track? What practical limits are there on SF2 size?

In response: Sound Font 2 and DLS samples are loaded only on an as-needed basis. There are practical limits on SF2 files, depending on how the file is laid out and how many of the samples in the file are used for a particular playback situation. Apart from memory availability, the size of the files (and even the size of the samples) are not an issue. If the memory is available, QTMA will use it.

There are some known limitations on both SF2 and DLS files, however.

1. Both formats have an internal name field for the entire sound bank. This should be set by the author of these files to be a meaningful name unique to that set.

QTMA uses this field as a way of identifying which sample bank is used if you assign an instrument to that bank. This is also the name that is used in the Instrument Picker dialog to allow users to assign parts (read MIDI Channels) of a music file to different sound banks.

1. Any use of the LSB as a way of selecting banks of sounds is not supported. This is only an option in DLS files. (SF2 files only supply the MSB for bank selects.)

For instance: (DLS only)

Bank-MSB Bank-LSB Patch Number

0 1 1

0 2 1

will result in the first patch being selected in both situations, as QTMA will only match on

Bank-MSB Patch Number

0 1

Assigning Custom Sound Banks to Movies

In general, music movies are made by importing a MIDI file into a QuickTime movie. During the import, no specific assignment of a part (or MIDI Channel) is assigned to an instrument. Thus, when a movie is played back, the default synthesizer that the user has selected in the QTMA Control Panel is used to render the parts of the movie.

Using QuickTime Player Pro, however, an author can assign particular synthesizers as well as different sound banks to a movie. To accomplish this, you follow these steps:

1. Open the Movie and choose “Get Movie Properties” from the “Movie” Menu.

2. When the dialog appears, choose the “Music Track” item in the top left pop-up menu.

3. In the top right pop-up menu, choose the “Instruments” item.

You now see a displayed all the parts found in this music track. Each part is signified by the name of the instrument used to render that part.

1. Double-click the instrument that you want to change. A dialog appears called the “Instrument Picker”, which shows you a list of the currently available sound banks and synthesizers.

2. You can choose a new sound bank with the top menu item. It will read “Default Synthesizer” initially.

Once you choose the sound bank you want to use for that part, you can choose the instrument from the sound bank you wish to use.

If you save the movie, the assigned sound bank is used during playback. Bear in mind that this sound bank will be searched for when you next open that movie, and should be present for the movie to be played back correctly.

Panorama Flags Superseded by the panoType Field

flags

A set of panorama flags. kQTVRPanoFlagHorizontal has been superseded by the panoType field. It is only used when the panoType field is nil to indicate a horizontally-oriented cylindrical panorama (for backwards compatibility with QuickTime 4).

panoType

An OSType describing the type of panorama. Types supported are

kQTVRHorizontalCylinder

kQTVRVerticalCylinder

kQTVRCube

reserved2

Reserved. This field must be 0.

Panorama Image Track

The actual panoramic image for a panoramic node is contained in a panorama image track, which is a standard QuickTime video track. The track reference to this track is stored in the imageRefTrackIndex field of the panorama sample atom.

Previous versions of QuickTime VR required the original panoramic image to be rotated 90 degrees counterclockwise. This orientation was changed in QuickTime 5 to allow either rotated (the previous requirement) or non-rotated tiles (the preferred orientation).

The rotated image is diced into smaller frames, and each diced frame is then compressed and added to the video track as a video sample, as shown in Figure 1-38. Frames can be compressed using any spatial compressor; however, temporal compression is not allowed for panoramic image tracks.

QuickTime 5 does not require the original panoramic image to be rotated 90 degrees counterclockwise, as was the case in previous versions of QuickTime VR. The rotated image is still diced into smaller frames, and each diced frame is then compressed and added to the video track as a video sample, as shown in Figure 1-39.

In QuickTime 5, a panorama sample atom (which contains information about a single panorama) contains the panoType field, which indicates whether the diced panoramic image is oriented horizontally or vertically.

New Cubic Panorama

A new type of panorama, the cubic panorama, is introduced in QuickTime 5. The cubic panorama in its simplest form is represented by six faces of a cube, thus enabling the viewer to see all the way up and all the way down. The file format and the cubic rendering engine actually allow for more complicated representations, such as special types of cubes with elongated sides or cube faces made up of separate tiles. Atoms that describe the orientation of each face allow for these nonstandard representations. If these atoms are not present, then the simplest representation is assumed. The following describes this simplest cubic representation: a cube with six square sides.

Tracks in a cubic movie are laid out as they are for cylindrical panoramas. This includes a QTVR track, a panorama track, and an image track. Optionally, there may also be a hot spot track and a fast-start preview track. The image, hot spot, and preview tracks are all standard QuickTime video tracks.

Image Tracks in Cubic Nodes

For a cubic node the image track contains six samples that correspond to the six square faces of the cube. The same applies to hot spot and preview tracks. The following diagram shows how the order of samples in the track corresponds to the orientation of the cube faces.

Note that by default the frames are oriented horizontally. However, arbitrary orientations (90 degrees clockwise, 90 degrees counterclockwise, upside down, and diamond shaped) can be used if specified with the 'cufa' atom. Still, the greatest rendering speed is used with horizontally oriented tiles.

Panorama Tracks in Cubic Nodes

The media sample for a panorama track contains the pano sample atom container. For cubes, some of the fields in the pano sample data atom have special values, which provide compatibility back to earlier versions of QuickTime VR. The cubic projection engine ignores these fields. They allow one to view cubic movies in older versions of QuickTime using the cylindrical engine, although the view will be somewhat incorrect, and the top and bottom faces will not be visible. The special values are shown in Table 1-1.

A 1 value in the flags field tells QuickTime VR that the frames are not rotated. QuickTime VR treats this as a four-frame horizontal cylinder. The panoType field (formerly reserved1) must be set to kQTVRCube ('cube') so that QuickTime 5 can recognize this panorama as a cube.

Since certain of the viewing fields in the pano sample data atom are being used for backward compatibility, a new atom must be added to indicate the proper viewing parameters for the cubic image. This atom is the cubic view atom (atom type 'cuvw'). The data structure of the cubic view atom is as follows:

struct QTVRCubicViewAtom {

    Float32 minPan;

    Float32 maxPan;

    Float32 minTilt;

    Float32 maxTilt;

    Float32 minFieldOfView;

    Float32 maxFieldOfView;

    Float32 defaultPan;

    Float32 defaultTilt;

    Float32 defaultFieldOfView;

};

typedef struct QTVRCubicViewAtomQTVRCubicViewAtom;

The fields are filled in as desired for the cubic image. This atom is ignored by older versions of QuickTime VR. Typical values for the min and max fields are shown in Table 1-2.

You add the cubic view atom to the pano sample atom container (after adding the pano sample data atom). Then use AddMediaSample to add the atom container to the panorama track.

Usage

An application will want to use the Gamma APIs in order to specify the gamma of a PixMap that it will compress or to request and verify the gamma of a PixMap that it decompresses.

In compression, it is sufficient to set the gamma of the PixMap using either QTSetPixMapPtrGammaLevel or QTSetPixMapHandleGammaLevel. Codecs will use this value when compressing the PixMap.

In decompression, the application can either request a gamma via QTSetPixMapPtrRequestedGammaLevel or QTSetPixMapHandleRequestedGammaLevel. The application can either request a specific gamma value, or the platform default or the native source gamma. Calling QTGetPixMapPtrGammaLevel or QTGetPixMapHandleGammaLevel after decompressing will return the actual gamma level of the decompressed data. During decompression, the requested gamma level of a PixMap does not change, which means that the same PixMap can have different gamma levels after different sources are decompressed. Applications should always check the gamma level after decompressing if they use either of the two requested gamma level APIs.

Codecs need to pay attention to the gamma level of the source buffer when compressing. Some compressed data (such as DV) is stored only with one gamma level (DV - 2.2) and the gamma is explicit for that format. These codecs should check the source gamma level and perform gamma correction when compressing as necessary.

Others, such as JPEG, could have different gamma levels depending on the source value, and can store the gamma value of the compressed data in a 'gama' or 'colr' ImageDescription extension without needing to convert the image.

In decompression, Codecs need to store the source and destination gamma levels received via ImageCodecRequestGammaLevel and correct the gamma based on the ratio of the two values.

PixMap APIs

The following APIs can be used to access gamma information stored as PixMap extensions.

QTGetPixMapPtrGammaLevel

Retrieves the current PixMap’s gamma level.

Fixed QTGetPixMapPtrGammaLevel( PixMapPtr pm );

QTSetPixMapPtrGammaLevel

Sets the gamma level of a PixMap.

OSErr QTSetPixMapPtrGammaLevel( PixMapPtr pm, Fixed gammaLevel );

kQTUsePlatformDefaultGammaLevel

Default gamma of the platform (Mac: 1.8, Windows: 2.5).

kQTUseSourceGammaLevel

Leave the data in the gamma level of the source data rather than converting.

kQTCCIR601VideoGammaLevel

Gamma 2.2 for ITU-R BT.601 based video.

QTGetPixMapHandleGammaLevel

Retrieves the current PixMap’s gamma level.

Fixed QTGetPixMapHandleGammaLevel( PixMapHandle pm );

QTSetPixMapHandleGammaLevel

Sets the gamma level of a PixMap.

OSErr QTSetPixMapHandleGammaLevel( PixMapHandle pm, Fixed gammaLevel );

kQTUsePlatformDefaultGammaLevel

Default gamma of the platform (Mac: 1.8, Windows: 2.5)

kQTUseSourceGammaLevel

Leave the data in the gamma level of the source data rather than converting.

kQTCCIR601VideoGammaLevel

Gamma 2.2 for ITU-R BT.601 based video.

QTGetPixMapPtrRequestedGammaLevel

Retrieves the current PixMap’s requested gamma level.

Fixed QTGetPixMapPtrRequestedGammaLevel( PixMapPtr pm );

QTSetPixMapPtrRequestedGammaLevel

Sets the requested gamma level of a PixMap.

OSErr QTSetPixMapPtrGammaLevel(PixMapPtr pm, Fixed requestedGammaLevel);

kQTUsePlatformDefaultGammaLevel

Default gamma of the platform (Mac: 1.8, Windows: 2.5)

kQTUseSourceGammaLevel

Leave the data in the gamma level of the source data rather than converting.

kQTCCIR601VideoGammaLevel

Gamma 2.2 for ITU-R BT.601 based video.

QTGetPixMapHandleRequestedGammaLevel

Retrieves the current PixMap’s requested gamma level.

Fixed QTGetPixMapHandleRequestedGammaLevel( PixMapHandle pm );

QTSetPixMapHandleRequestedGammaLevel

Sets the requested gamma level of a PixMap.

OSErrQTSetPixMapHandleRequestedGammaLevel( PixMapHandle pm, Fixed  requestedGammaLevel );

kQTUsePlatformDefaultGammaLevel

Default gamma of the platform (Mac: 1.8, Windows: 2.5)

kQTUseSourceGammaLevel

Leave the data in the gamma level of the source data rather than converting.

kQTCCIR601VideoGammaLevel

Gamma 2.2 for ITU-R BT.601 based video.

Codec APIs

The following APIs are defined for codecs to support gamma conversion

ImageCodecRequestGammaLevel

Requests the codec to convert from source to destination gamma levels.

ComponentResult ImageCodecRequestGammaLevel( ComponentInstance ci, Fixed  srcGammaLevel, Fixed dstGammaLevel, long *codecCanMatch )

ImageCodecGetSourceDataGammaLevel

Requests the native gamma of the compressed data, if any.

ComponentResult ImageCodecGetSourceDataGammaLevel( ComponentInstance ci, Fixed  *sourceDataGammaLevel )

Default Gamma of Custom Pixel Formats

Third-party developers can specify the default gamma for PixMaps using custom pixel formats by setting the defaultGammaLevel field in the ICMPixelFormatInfo structure. This structure can be registered by calling ICMSetPixelFormatInfo when the codec opens.

How To Find All Clone Tracks in a Movie

A clone Track maintains a track reference of type 'csrc' (“clone source”) to the Track owning the sample table. In order to find all clone Tracks in a Movie and their master tracks, you can use code similar to the following:

Listing 1-7  Finding all clone tracks in a movie

long trackCount, trackIndex;

Track currentTrack, masterTrack;

trackCount = GetMovieTrackCount(theMovie);

for (trackIndex = 1; trackIndex <= trackCount; trackIndex++)

{

    currentTrack = GetMovieIndTrack(theMovie, trackIndex);

    masterTrack = GetTrackReference(currentTrack, ‘csrc’, 1);

    if (masterTrack != nil) {

    // currentTrack is a clone track

    // masterTrack owns the sample table for currentTrack

    }

}

Because a Track may be cloned multiple times, there may be more than one clone Track with the same master Track.

Notes and Issues

In its initial implementation, you should be aware of the following issues in using AddClonedTrackToMovie. These limitations will be relaxed in time.

• The source and cloned Tracks must be in the same Movie.

• Only sample table sharing is supported. Always include kQTCloneShareSamples in the flags to AddClonedTrackToMovie.

• A movie containing cloned tracks can be stored in a public movie resource while preserving the cloning relationships.

• Note that movies containing cloned tracks will fail to open in earlier versions of QuickTime because of changes in the public movie format.

• Flattening a movie containing clone tracks works. However, the data sharing is not preserved in the flattening process. Each track’s referenced media data is written to disk just as it would be with independent tracks.

• Editing of clone Tracks is limited to Track-level edit list operations. These include: InsertEmptyTrackSegment, InsertTrackSegment, InsertMediaIntoTrack, DeleteTrackSegment, and ScaleTrackSegment. Movie-level editing operations such as AddMovieSelection, CutMovieSelection, and InsertMovieSegment will give undefined results. Track level, media-related editing on non-clone tracks should work.

• Attempting to modify the sample table of a clone track using operations such as AddMediaSample, AddSampleDescription will return the new error cannotModifyMediaErr (= -2161). Such changes to the Track owning the sample table, however, is allowed and these modifications will propagate to clone tracks.

• Exporting should work, unless the exporter depends upon movie segment based editing operations. QuickTime’s exporters typically use PutMovieIntoHandle and NewMovieFromHandle when they need to make temporary movies.

New APIs

The following APIs have been added to the Movie Toolbox and the Media Handler API:

SetMovieVideoOutput

Indicates to the ICM the video output component being used with the given movie.

void SetMovieVideoOutput(Movie theMovie, ComponentInstance vout)

New Media Handler API

The following Media Handler API has been added to QuickTime 5:

MediaEmptySampleCache

Empties any sample data that the media handler has cached.

ComponentResult MediaEmptySampleCache(MediaHandler mh, long sampleNum, long  sampleCount)

Pointer Data Handler

The Pointer data handler adds to the complement of other QuickTime data handlers. Like the Handle Data Handler, the Pointer data handler supports references to data in memory; unlike the Handle data handler, the Pointer data handler does not require that data reside within a block allocated by the Macintosh Memory Manager. You just specify the memory address of the data and its length, and the Pointer data handler will do the rest.

The Pointer data handler allows you to submit data for use by QuickTime via direct memory address. However, it does not eliminate the use of handles in QuickTime’s data handler API. Data references themselves are still stored in handles on which QuickTime will call GetHandleSize. The API also requires that ancillary pieces of information about data references, such as their names and MIME types, are passed to QuickTime in handle blocks, not pointer blocks.

A pointer data ref record has the following definition:

struct PointerDataRefRecord {

    void        *data;

    Size        dataLength;

};

typedef PointerDataRefRecord *PointerDataRefPtr;

typedef PointerDataRefPtr *PointerDataRef;

The code snippet in Listing 1-8 shows you how you can open media at a specific memory address as a QuickTime movie. The snippet does not include error checking.

Listing 1-8  Opening media at a specific memory address as a QuickTime movie

     Str255 mimeTypePascalStr;

     Str255 namePascalStr;

     Handle dataRefXtnsnHndl;

     ComponentInstance dataHandler;

     PointerDataRef dataref =

                (PointerDataRef)NewHandle(sizeof(PointerDataRefRecord));

     (**dataref).data = myPointerToSomeMedia;

     (**dataref).dataLength = theLengthOfTheMedia;

     osstat = OpenADataHandler(dataRef, PointerDataHandlerSubType, nil,

                            (OSType)0, nil, kDataHCanRead, &dataHandler);

     // mix in the the mime type of the media

     osstat = PtrToHand(mimeTypePascalStr, &dataRefXtnsnHndl,

                        mimeTypePascalStr[0]+1);

     osstat = DataHSetDataRefExtension(dataHandler, dataRefXtnsnHndl,

                                        kDataRefExtensionMIMEType);

     DisposeHandle(dataRefXtnsnHndl);

     // mix in the name of the media

     osstat = PtrToHand(namePascalStr, &dataRefXtnsnHndl, namePascalStr

                        [0]+1);

     osstat = DataHSetDataRefExtension(dataHandler, dataRefXtnsnHndl,

                                        kDataRefExtensionFileName);

     DisposeHandle(dataRefXtnsnHndl);

     // don't need our data handler instance anymore

     CloseComponent(dataHandler);

     // make a movie

     osstat = NewMovieFromDataRef(&newMovie, newMovieActive +

                                    newMovieIdleImportOK +

                                    newMovieAsyncOK, &newResID, dataref,

                                    PointerDataHandlerSubType);

New Load State Defined

QuickTime 5 introduces a new load state, defined for the call GetMovieLoadState, between kMovieLoadStatePlayable and kMovieLoadStateComplete called kMovieLoadStatePlaythroughOK. This value will be returned after the movie has become playable, as soon as QuickTime calculates that the download would complete before the playback would complete. As previously, when a download completes, GetMovieLoadState returns kMovieLoadStateComplete.

Autoplay and the Movie Toolbox

mcActionAutoPlay is a new movie controller action introduced in QuickTime 5 that enables you to start a QuickTime movie playing automatically as soon as there is a sufficient amount of data available to play it to completion. This mirrors behavior previously available only in the QuickTime Plugin.

mcActionAutoPlay enables support for a feature such as QuickTime Player’s autoplay, which allows you to automatically begin playback of a movie as soon as it is appropriate. If it is a movie that is being transferred via HTTP, for example, it won’t start to play until QuickTime calculates that the download would complete before the playback would complete.

New Media Type Supported

A new media type is introduced in QuickTime 5. The GSM Importer, a new movie importer defined by the file extension .gsm, the file type 'GSM ', and the MIME type audio/x-gsm, is used to handle new media configurations specified by the QuickTime Plugin and the control panel in QuickTime 5.

New Embed Tag Parameters

The QuickTime browser plugin accepts two new EMBED tag parameters and a new URL extension that allows you to specify a set of EMBED tag parameters as part of a URL.

EMBED tag parameters are normally specified in HTML code as part of the EMBED tag. However, parameter values can also be stored inside a movie –– typically by an application such as Plugin Helper. And some parameters, such as AUTOPLAY, can also have their value set by user preferences.

This makes it possible to specify different settings for the same parameter in different places. You could set AUTOPLAY=True in your HTML, for example, while embedding AUTOPLAY=False in the movie using Plugin Helper. QuickTime resolves any such conflicts by giving first priority to HTML, next priority to settings embedded using Plugin Helper, and last priority to settings specified by user preferences.

As each parameter’s value is set by one of these methods, it is flagged to prevent its value from being overridden by a lower priority method. Unflagged parameters can still be set, allowing all methods to operate as long as none conflict.

The EMBED tag parameter settings can change when one movie replaces another, through the use of the QTNEXT or HREF parameter, for example, or through the action of an HREF track or a VR hotspot.

When one movie replaces another as specified in the QTNEXT parameter, the new movie inherits its parameter values from the current movie. Any values set in the HTML or embedded in the first movie are flagged, and take precedence over any values embedded in the new movie or the user preferences.

When one movie replaces another as specified in the HREF parameter, or as the result of an HREF Track action or a VR hotspot, the EMBED tag parameters are all reset to their default values. They are not flagged, however, so the defaults can be overridden by embedding the desired settings in the new movie.

The new EMBED tag parameters and URL extensions introduced in QuickTime 5 give you more control over these behaviors. You can now specify a set of explicit parameter values as part of a URL, instead of having to embed them in the new movie. You can also specify whether a new movie should inherit the current settings, and whether the current settings may be overridden (by settings embedded in the new movie or by the user preferences).

New URL Extensions

Some EMBED tag parameters, such as HREF, HOTSPOT, and QTNEXT, allow you to specify a URL. The QuickTime plugin can also parse URLs from HREF Tracks or text tracks inside a movie. A QuickTime URL extension allows these URLs to include a target, specified as part of the URL, using the syntax "<URL> T<target>". Note that the URL and the target specification are surrounded separately by angle brackets, and that quotes surround the URL and the extension jointly.

QuickTime 5 introduces a new URL extension that allows you to specify a separate set of EMBED tag parameters for each movie as part of the URL. This is easier and more flexible than having to embed settings in a movie using Plugin Helper, and it can be accomplished automatically at the HTML level by any script that can output a text file. The syntax is:

"<URL> T<Target> E<ParamA=Value ParamB=Value ... >"

For example, this code:

< EMBED SRC=Movie1.mov HEIGHT=256 WIDTH=320 CONTROLLER=False HREF="<Movie2.mov> T<myself> E<CONTROLLER=True AUTOPLAY=True>" >

uses HTML EMBED tag parameters to tell the QuickTime plugin to play Movie1.mov with no controller, leaving the AUTOPLAY parameter unspecified (controlled by user preferences). If the viewer clicks inside the display area of the movie, the HREF parameter tells the plugin to load Movie2.mov. The URL extensions T<> and E<> tell the plugin to replace the current movie (T<myself>), and set AUTOPLAY=True and CONTROLLER=True (E<AUTOPLAY=True CONTROLLER=True>).

Again, note that the URL itself is surrounded by angle brackets, and that a set of quotes surrounds the URL and all extensions.

Parameter values set using this method take precedence over any values embedded in the new movie using Plugin Helper or set by user preferences. You can change this using the new AllowEmbedTagOverrides parameter.

SaveEmbedTags

You can tell the QuickTime browser plugin to apply the current parameter values to a new movie by setting SaveEmbedTags=True. This causes a movie specified in an HREF parameter, for example, to behave like a movie loaded using the QTNEXT parameter — it inherits the current parameter values instead of being reset to the default values.

Example:

<EMBED SRC=ClickMe.mov HEIGHT=240 WIDTH=320 AUTOPLAY=True CONTROLLER=False LOOP=True HREF=YouClickedIt.mov TARGET=myself SAVEEMBEDTAGS=True >

This example would cause the plugin to autoplay ClickMe.mov in an endless loop with no controller. If the viewer clicked inside the movie’s display area, the plugin would load YouClickedIt.mov, which would also autoplay in a loop with no controller.

Like the values inherited through use of the QTNEXT parameter, the parameter values set using this method take precedence over any values embedded in the new movie using Plugin Helper or set by user preferences. You can change this using the new AllowEmbedTagOverrides parameter.

AllowEmbedTagOverrides

Setting the AllowEmbedTagOverrides parameter allows you to control whether the current parameter settings can be overridden by lower priority methods. This parameter can be set within your HTML or by embedding the parameter value in a movie, or both.

By default, EMBED tag parameter values set in HTML have higher priority than values embedded in a movie, which in turn take priority over user preferences. Similarly, when a movie inherits parameter values (because of the QTNEXT or SaveEmbedTags parameters), these inherited values take precedence over any values embedded in the movie itself, or specified by user preferences.

If you set AllowEmbedTagOverrides=True in your HTML, however, the current settings can be overridden by settings embedded in a movie using Plugin Helper, which in turn can be overridden by user preferences.

Bear in mind that this affects only parameters whose value you explicitly set. If you do not set a parameter’s value in your HTML, for example, that parameter can always be set by Plugin Helper or by the user preferences.

You would normally set AllowEmbedTagOverrides=True in your HTML to allow settings embedded in a new movie to take precedence over the current settings.

For example, when a new movie is specified by the QTNEXT parameter, or when the SaveEmbedTags parameter is set true, the new movie inherits the current parameter settings, and these settings take precedence over settings embedded in the new movie. By setting AllowEmbedTagOverrides to true, you can cause the new movie to inherit the current settings as default values, but override them with any settings embedded in the new movie.

Example:

<EMBED SRC=ClickMe.mov HEIGHT=240 WIDTH=320 CONTROLLER=False HREF=YouClickedIt.mov TARGET=myself SaveEmbedTags=True AllowEmbedTagOverrides=True >

In this example, when the viewer clicks in the display area of ClickMe.mov, the plugin loads YouClickedIt.mov. Because SaveEmbedTags is set True, the new movie inherits the parameter values set in the HTML (CONTROLLER=False) as well as any parameter settings embedded in ClickMe.mov, but because AllowEmbedTagOverrides is also true, these act as defaults that can be overriden by any settings embedded in YouClickedIt.mov, which could, for example, set CONTROLLER=True.

Note that when AllowEmbedTagOverrides=True, the AUTOPLAY parameter is controlled by the user’s QuickTime Settings control panel. If you set AllowEmbedTagOverrides=True in your HTML, and you want to control the AUTOPLAY parameter, you need to set AllowEmbedTagOverrides=False inside the new movie using a tool such as Plugin Helper. Otherwise, your setting will be overriden by the user’s preferences.

New Debug Tool Added to Plugin

QuickTime 5 adds a new tool to the Plugin that will help debug wired movies. The tool, which is simple and easy to use, is intended for QuickTime developers who are working specifically with wired movies. It works in this manner:

When the plug-in finds a media key named QTPIShowDebugMessages with the value “alert,” it puts up a dialog whenever it gets a sprite debug message. If the value is “debugger,” it drops into the low-level debuggeer (MacsBug or whatever is installed on your machine).

Idling Mechanism Re-Worked

The way in which time-based callbacks work in QuickTime for Java has been re-engineered. These callbacks are now triggered off interrupts or very high priority native threads, in the case of Mac OS X and Windows, rather than as previously triggered explicitly by QuickTime for Java calls to MoviesTask, which meant that QuickTime for Java had to create idling threads in order to make the callbacks fire.

Timing callbacks are used in the QuickTime for Java compositing services, like the Compositor Class, and are used to render frames when you set the rate of the Compositor to a rate that is not equal to zero. This gives QuickTime for Java much better performance because the callbacks are delivered executing Java code much closer to when they should be. This also means that you don't have to have an idling thread running in order to have these callbacks fire in the first place. If your application is using the time callbacks themselves, you don’t have to instantiate any sort of idling mechanism, as you would have done in the past. These callbacks will just fire when the time conditions are met. This results in a much more responsive system.

Support for New Services

QuickTime for Java also provides support for a number of new QuickTime services, including

• The Broadcasting APIsthat are new in QuickTime 5 (see the quicktime.streaming package). These classes will only work on the Mac OS because that feature is only supported by QuickTime on Mac OS.

• APIs forXML Event-Based Parsing that are also new with QuickTime 5 (see the quicktime.std.qtcomponents package).

• Enhanced API support for Sound Manager services. Asynchronous recording is now supported. SndChannels can be instantiated with a callback, enabling asynchronous playback, use of the soundCmd (like bufferCmd). SndChannels can also be queried for equalization settings, and Spectral Data, including a new EQ component in QuickTime 5 that allows up to 64 bands of spectral data to be obtained.

In response to requests from developers, the QTFilter and QTTransition classes now support movies, compositors as sources, as well as still images.

There are, in addition, a number of minor enhancements and bug fixes in this release.

The JavaDoc for all of these new APIs in QuickTime for Java can be perused at:

http://developer.apple.com/quicktime/qtjava

QTDrawing Listener and Notification Services

Two new classes have been added to QuickTime for Java that provide notification services for DynamicImage classes upon completion of drawing operations. For notification of drawing operations, the DrawingNotifier interface is used, and the DrawingListener interface is used to register interest in drawing complete notifications.

Several QTJ classes were modified to use the DrawingNotifier interface: MoviePlayer, MoviePresenter, QTEffectPresenter, and SWCompositor. These classes provide a method addDrawingListener() that you may call to register your class.

Once your class that implements the DrawingListener interface is registered, you will get called whenever a drawing operation occurs on the Notifier object. This is useful, for example, if you want to know when a frame has been rendered in a Movie.

To make a class that uses the DrawingListener interface, you need to do the following:

public class MyListener implements DrawingListener {

    public void drawingComplete (QTDrawable drawable) {

        // do something cool when notification is received

    }

}

And then register your class with the component:

MyListener listener = new MyListener();

    // register MyListener w/ SWCompositor

theCompositor.addDrawingListener (listener);

When you no longer want to receive drawing notifications, call removeDrawingListener() with your DrawingListener object from the component you are no longer interested in.

New SMIL Attributes

qt:fullscreen="fullscreen_false"

qt:fullscreen="fullscreen_normal"

qt:fullscreen="fullscreen_double"

qt:fullscreen="fullscreen_half"

qt:fullscreen="fullscreen_full"

qt:fullscreen="fullscreen_current"

URL Resolution

In QuickTime 5, SMIL and HTML documents can now use BASE URLs that point to directories. For example:

file:///mydrive/dir1/dir2/lookhere/

SMIL and HTML documents can also use BASE URLs that point to dummy entries, as long as their parent directories are valid. For example:

file:///mydrive/dir1/dir2/lookhere/bogus.html

Broadcasting APIs

The new QuickTime broadcasting APIs are designed to allow you to create standards-compliant RTP broadcasts. This means that non-QuickTime clients can play back your broadcasts. The new APIs comprise part of the QTSPresentation API related to broadcasting and the QTSSourcer component API. (Note that these new broadcasting APIs currently work only on the Mac OS, with a limited set provided on Mac OS X.)

Basic broadcasting support of the following is included in the QuickTime 5 release:

• Audio and video streams from the Sequence Grabber.

• Stored movies, i.e., audio and video.

• Text and URLs.

• Configuration settings with dialogs and info selectors.

• The ability to broadcast for extended periods of time without restarting.

• The ability to broadcast data from different sources (sourcer components).

The QuickTime-supplied sourcers in this release include:

• Sequence Grabber (audio and video only).

• Precompressed media, i.e., sourcer that takes a sample description and sample data.

• Stored movies.

• The ability to dynamically switch sourcers, e.g., dynamically switch from a live feed to a stored movie.

• Reporting of basic statistics, e.g., number of connected users or network stats.

Broadcasting with these new APIs is straightforward enough. The process works as follows: When you’re broadcasting, QuickTime uses the Sequence Grabber to source the media as the default. If you want to generate your own data, your application can create a sample description, with a piece of data, and an accompanying timestamp. Then you call the new broadcast APIs and the data will be broadcast.

New Wired Actions

The following new wired actions have been added in QuickTime 5:

• General

• Send App Message

• Flash

• Text

• QTLists

• Track

• QTVR

kActionLoadComponent = 6161, /* (ComponentDescription handlerDesc) */

kActionSetFocus = 6162, /* [(TargetAtoms theObject)] */

enum {

    kTargetObjectName = FOUR_CHAR_CODE('obna'), /* (PString objectName) */

    kTargetObjectID  = FOUR_CHAR_CODE('obid'),  /* (QTAtomID objectID) */

    kTargetObjectIndex  = FOUR_CHAR_CODE('obin') /* (short objectIndex) */

};

kActionDontPassKeyEvent = 6163, /* no params */

kActionSendAppMessage = 6160,        /* (long appMessageID) */

kQTAppMessageSoftwareChanged = 1,       /* notification to app that

                                        installed QuickTime

                                        software has been updated*/

kQTAppMessageWindowCloseRequested = 3,  /* request for app to close

                                        window containing

                                        movie controller*/

kQTAppMessageExitFullScreenRequested = 4/* request for app to turn off

                                        full screen mode if active*/

kQTAppMessageEnterFullScreenRequested = 6

kActionFlashTrackSetFlashVariable = 10245, /* (C string path, C string name, C  string

                                            value, Boolean updateFocus) */

kActionFlashTrackDoButtonActions = 10246,/* (C string path, long buttonID, long

                                            transition) */

kActionTextTrackPasteText = 12288,/* (C string theText, long startSelection, long

                                        endSelection ) */

kActionTextTrackSetTextBox = 12291,/* (short left, short top, short right,

                                    short bottom) */

kActionTextTrackSetTextStyle = 12292,/* (Handle textStyle) */

kActionTextTrackSetSelection = 12293,/* (long startSelection, long endSelection )  */

kActionTextTrackSetBackgroundColor = 12294,/* (ModifierTrackGraphicsModeRecord

                                                backgroundColor ) */

kActionTextTrackSetForegroundColor = 12295,/* (ModifierTrackGraphicsModeRecord

                                            foregroundColor ) */

kActionTextTrackSetFace = 12296,/* (long fontFace ) */

kActionTextTrackSetFont = 12297,/* (long fontID ) */

kActionTextTrackSetSize = 12298,/* (long fontSize ) */

kActionTextTrackSetAlignment = 12299,/* (short alignment ) */

    teJustLeft                  = 0,

    teJustCenter                = 1,

    teJustRight                 = -1,

    teForceLeft                 = -2, /* new names for the

                                 Justification (word alignment) styles */

    teFlushDefault              = 0, /*flush according to the line

                                 direction */

    teCenter                    = 1, /*center justify (word alignment) */

    teFlushRight                = -1,/*flush right for all scripts */

kActionTextTrackSetHilite = 12300,/* (long startHighlight, long endHighlight,

                                    ModifierTrackGraphicsModeRecord  highlightColor ) */

kActionTextTrackSetDropShadow = 12301,/* (Point dropShadow, short transparency ) */

kActionTextTrackSetDisplayFlags = 12302,/* (long flags ) */

    dfDontDisplay               = 1 << 0,   /* Don't display the text*/

    dfDontAutoScale             = 1 << 1,   /* Don't scale text as track bounds  grows

                                                or shrinks*/

    dfClipToTextBox             = 1 << 2,   /* Clip update to the textbox*/

    dfUseMovieBGColor           = 1 << 3,   /* Set text background to movie's

                                                background color*/

    dfShrinkTextBoxToFit        = 1 << 4,   /* Compute minimum box to fit the  sample*/

    dfScrollIn                  = 1 << 5,   /* Scroll text in until last of text  is in

                                                view */

    dfScrollOut                 = 1 << 6,   /* Scroll text out until last of text  is

                                            gone (if both set, scroll in then  out)*/

    dfHorizScroll               = 1 << 7,   /* Scroll text horizontally  (otherwise it's

                                                vertical)*/

    dfReverseScroll             = 1 << 8,   /* vert: scroll down rather than up;  horiz:

                                            scroll backwards (justfication  dependent)*/

    dfContinuousScroll          = 1 << 9,   * new samples cause previous samples  to

                                            scroll out */

    dfFlowHoriz                 = 1 << 10,  /* horiz scroll text flows in textbox

                                                rather than extend to right */

    dfContinuousKaraoke         = 1 << 11,  /* ignore begin offset, hilite  everything

                                                up to the end offset(karaoke)*/

    dfDropShadow                = 1 << 12,  /* display text with a drop shadow */

    dfAntiAlias                 = 1 << 13,  /* attempt to display text anti  aliased*/

    dfKeyedText                 = 1 << 14,  /* key the text over background*/

    dfInverseHilite             = 1 << 15,  /* Use inverse hiliting rather than  using

                                                hilite color*/

    dfTextColorHilite           = 1 << 16   /* changes text color in place of

                                                hiliting. */

kActionTextTrackSetScroll = 12303,/* (long delay ) */

kActionTextTrackRelativeScroll = 12304,/* (short deltaX, short deltaY ) */

kActionTextTrackFindText = 12305,/* (long flags, Str255 theText,

                                    ModifierTrackGraphicsModeRecord  highlightColor ) */

kActionTextTrackSetHyperTextFace = 12306,/* (short index, long fontFace ) */

kActionTextTrackSetHyperTextColor = 12307,/* (short index,

                                    ModifierTrackGraphicsModeRecord  highlightColor ) */

kActionTextTrackKeyEntry = 12308,/* (short character ) */

kActionTextTrackSetEditable = 12310,/* (short editState) */

    #define kKeyEntryDisabled       0

    #define kKeyEntryDirect         1

    #define kKeyEntryScript         2

kActionTextTrackMouseDown = 12309,/* no params */

kActionListSetFromURL = 13317       /* (C string url, C string targetParentPath )  */

kActionListAddElement = 13312,/* (C string parentPath, short atIndex, C string

                                newElementName) */

kActionListRemoveElements = 13313,/* (C string parentPath, short startIndex, short

                                        endIndex) */

kActionListSetElementValue = 13314,/* (C string elementPath, C string valueString)  */

kActionListPasteFromXML = 13315,/* (C string xml, C string targetParentPath, short

                                    startIndex) */

kActionListSetMatchingFromXML = 13316/* (C string xml, C string targetParentPath)  */

kActionListServerQuery = 13319 /* (C string url, C string keyValuePairs, long flags,  C

                                string parentPath) */

enum    {

    kListQuerySendListAsXML             = 1,

    kListQuerySendListAsKeyValuePairs   = 2,

    kListQueryWantCallback              = 4,

    kListQueryDebugTrace                = 8

};

url?key1=one&key2=two&key3=three.

url?qtlist=<qtlist><key1>one</key1><key2>two</key2><key3>three</key3></qtlist>

url?user=joe&qtlist=<qtlist><key1>one</key1><key2>two</key2><key3>three</key3></ qtlist>

kActionTrackSetIdleFrequency = 2056, /* (long frequency) */

kActionTrackSetBassTreble = 2057, /* (short base, short treble) */

kActionQTVREnableHotSpot = 4101, /* long ID, Boolean enable */

kActionQTVRShowHotSpots = 4102, /* Boolean show */

kActionQTVRTranslateObject  = 4103, /* float xMove, float yMove *

New Wired Operands

kOperandEventParameter = 26,        /* short index */

        1 : where.h

        2 : where.v

        3 : modifiers

        1 : where.h

        2 : where.v

        3 : modifiers

        4 : key

        5 : scancode

kOperandFreeMemory = 27,

kOperandNetworkStatus = 28,

    kQTNetworkStatusNoNetwork   = -2,

    kQTNetworkStatusUncertain   = -1,

    kQTNetworkStatusNotConnected = 0,

    kQTNetworkStatusConnected   = 1

kOperandMovieDuration = 1029,

kOperandMovieTimeScale = 1030,

kOperandMovieWidth = 1031,

kOperandMovieHeight = 1032,

kOperandMovieLoadState = 1033,

    kMovieLoadStateLoading      = 1000,     kMovieLoadStatePlayable     = 10000,     kMovieLoadStatePlaythroughOK = 20000,     kMovieLoadStateComplete     = 100000L

kOperandMovieTrackCount = 1034,

kOperandTrackWidth = 2052,

kOperandTrackHeight = 2053,

kOperandTrackDuration = 2054,

kOperandTrackBass = 2058,

kOperandTrackTreble = 2059,

kOperandSpriteTrackSpriteIDAtPoint = 3094,/* short x, short y */

kOperandTextTrackEditable = 6144,

kOperandTextTrackCopyText = 6145,/* long startSelection, long endSelection */

kOperandTextTrackStartSelection = 6146,

kOperandTextTrackEndSelection = 6147,

kOperandTextTrackTextBoxLeft = 6148,

kOperandTextTrackTextBoxTop = 6149,

kOperandTextTrackTextBoxRight = 6150,

kOperandTextTrackTextBoxBottom = 6151,

kOperandListCountElements = 7168,/* (C string parentPath) */

kOperandListGetElementPathByIndex = 7169,/* (C string parentPath, short index) */

kOperandListGetElementValue = 7170,/* (C string elementPath) */

kOperandListCopyToXML = 7171,       /* (C string parentPath, short startIndex,

                                    short endIndex) */

kOperandSin                 = 8192,         /* float x  */

kOperandCos                 = 8193,         /* float x  */

kOperandTan                 = 8194,         /* float x  */

kOperandATan                = 8195,         /* float x  */

kOperandATan2               = 8196,         /* float y, float x */

kOperandDegreesToRadians    = 8197,         /* float x */

kOperandRadiansToDegrees    = 8198,         /* float x */

kOperandSquareRoot          = 8199,         /* float x */

kOperandExponent            = 8200,         /* float x */

kOperandLog                 = 8201,         /* float x */

kOperandFlashTrackVariable = 9216/* [CString path, CString name] */

kOperandSystemVersion = 30

/* flags for kOperandSystemVersion*/

enum {

    kSystemIsWindows9x = 0x00010000,

    kSystemIsWindowsNT = 0x00020000

};

kOperandMovieIsActive = 1035

kOperandStringLength = 10240,    /* (C string text) */

kOperandStringCompare = 10241,    /* (C string aText, C string bText, Boolean                                      caseSensitive, Boolan diacSensitive) */

kOperandStringSubString = 10242,    /* (C string text, long offset, long length) */

kOperandStringConcat = 10243     /* (C string aText, C string bText) */

kOperandQuickTimeVersionRegistered

kOperandMovieName = 1036,

kOperandMovieID = 1037,

kOperandTrackName = 2055,

kOperandTrackID = 2056,

kOperandTrackIdleFrequency  = 2057,

kOperandSpriteName = 3095,

kOperandQTVRHotSpotsVisible = 4100,

kOperandQTVRViewCenterH = 4101,

kOperandQTVRViewCenterV = 4102,

enum    {

    kTrackFocusCanEditFlag   = 'kedt' // Boolean

};

kOperandCanHaveFocus = 5124, /* [(TargetAtoms theObject)] */

kOperandHasFocus = 5125, /* [(TargetAtoms theObject)] */

New QuickTime Media Links XML Importer

QuickTime 5 introduces support for a new XML importer –– QuickTime Media Links. This is a small XML file that has similar attributes to the embed tag in HTML used for the plugin, but targets QuickTime Player instead of the plugin. This section discusses the supported attributes and values, and how to create the file.

To test the new QuickTime Media Links XML importer, you create a text file with the following two lines at the top of the file:

<?xml version="1.0"?>

<?quicktime type="application/x-quicktime-media-link"?>

Next, you add the embed tag itself:

<embed src="http://somewhere.com/Movies/test.mov" />

 autoplay - true/false

 controller - true/false

 fullscreen - normal/double/half/current/full

 href - url

 kioskmode - true/false

 loop - true/false/palindrome

 movieid - integer

 moviename - string

 playeveryframe - true/false

 qtnext - url

 quitwhendone - true/false

 src - url (required)

 type - mime type

 volume - 0 (mute) - 100 (max)

<embed src="http://somewhere.com/Movies/test.mov" autoplay />

<?quicktime type="application/x-quicktime-reference"?>

<?xml version="1.0"?>

<?quicktime type="application/x-quicktime-media-link"?>

<embed src="http://somewhere.com/Movies/test.mov"  autoplay="true"

            fullscreen="double"/>