Silicon Graphics uses a proprietary movie file format that has evolved over time to the current 3.0 version. You can read movies that use previous versions (1.0 and 2.0) of the file format—for example, movies that were created using the prerelease alphas of the Movie Library or previous releases of Movie Maker—but the Movie Library writes only Silicon Graphics version 3.0 movie files.

The Silicon Graphics version 3. 0 movie format is a parameterized file format with data that is normally interleaved. It currently consists of a single image track and an optional audio track.

See Chapter 31, “Using the Movie Library with QuickTime Movies,” for information on working with QuickTime movies and on using the optional Silicon Graphics QuickTime Compressor Library, which provides Movie Library support for both Apple Animation and Apple Video compression.

See Inside Macintosh: QuickTime for information about developing QuickTime applications, and see the QuickTime Starter Kit User's Guide for information on how to use the Apple QuickTime utilities on the Macintosh.

The destination system determines which movie format to choose when writing the final version of a movie file. Use the QuickTime format only if you require cross-platform compatibility between Silicon Graphics and Apple Macintosh computers.

The debugging version of the Movie Library checks for violations by setting assertions that rigidly state the requirements for a parameter or value. One typical assertion, worded in standard English, is: “Check that the current frame number is within the bounds of the number of frames in the movie,” which is more precisely stated in the following assertion:

ASSERT( 0 <= frame < trackLength, "Frame number out of range")

To use the debugging version of the library, link with libmovie_d.a as follows:

-lmovie_d

and then run your program.

Your application will abort with an error message if it fails an assertion. The message explains the situation that caused the error, and by implication or by explicit description, suggests a corrective action.

When you have finished debugging your application, you should relink with the nondebugging library, libmovie.a, because the runtime checks imposed by the debugging library cause an undesirable performance and size overhead for a packaged application.

When attempting to read data from a device such as a CD-ROM drive or over the network, two types of problems can occur:

You can test how your application handles these types of I/O failures by setting the following environment variables to emulate failures without causing actual failures:

To store a comment string in a movie file, call mvSetComment(). Its function prototype is:

DMstatus mvSetComment( MVid movie, const char* comment )

To retrieve the comment string that is stored in a movie file, call mvGetComment(). Its function prototype is:

const char* mvGetComment( MVid movie )

The Silicon Graphics movie file format lets you store a default loop mode setting within a movie file. When opening a movie file, the Movie Library obtains the default loop mode from the movie if it is set; otherwise, it assumes MV_LOOP_NONE is the default loop mode.

To store a default loop mode setting in a movie file, call mvSetLoopMode(). Its function prototype is:

DMstatus mvSetLoopMode( MVid movie, MVloopmode mode )

where:

You can set the playback loop mode independently of the default loop mode by using mvSetPlayLoopMode(), as described in “Looping” in Chapter 30.

To retrieve the loop mode setting that is stored in a movie file, call mvGetLoopMode(). Its function prototype is:

MVloopmode mvGetLoopMode( MVid movie )

You can store a default loop limit setting in the movie file that defines the default for the number of movie loops a movie will play if its loop mode is set to MV_LOOP_CONTINUOUSLY or MV_LOOP_SWINGING. To store a default loop limit in a movie file, call mvSetLoopLimit(). Its function prototype is:

DMstatus mvSetLoopLimit( MVid movie, int limit )

where:

To retrieve the default loop limit setting that is stored in a movie file, call mvGetLoopLimit(). Its function prototype is:

int mvGetLoopLimit( MVid movie )

To store a title string in a movie file, call mvSetTitle(). Its function prototype is:

DMstatus mvSetTitle( MVid movie, const char* title )

To retrieve the title string that is stored in a movie file, call mvGetTitle(). Its function prototype is:

const char* mvGetTitle( MVid movie )

To retrieve the file format of a movie file, call mvGetFileFormat(). Its function prototype is:

MVfileformat mvGetFileFormat( MVid movie )

mvGetFileFormat() returns the file format of the movie:

To determine whether a movie is optimized for playback, call mvGetOptimized(). Its function prototype is:

DMboolean mvGetOptimized( MVid movie )

mvGetOptimized() returns DM_TRUE if the movie is optimized for playback performance and DM_FALSE if it is not. Performing any editing operations on the movie that read, write, insert, or delete frames will disrupt the optimization and clear this flag. See “Optimizing a Movie File” in Chapter 29 for more information about movie optimization.

You can store SMPTE time codes as strings in a track parameter. The time code string does not have any relationship to a timer inside the Movie Library, so you have to obtain the time code from an external source before storing it as a parameter. See “Using the SMPTE Time Code Sample Application” in Chapter 32 for sample programs that implement time code capability.

To store a SMPTE time code string in a movie track, call mvSetSMPTEStart(). Its function prototype is:

DMstatus mvSetSMPTEStart(MVid movie, const char* start_time)

where:

mvSetSMPTEStart() returns either DM_SUCCESS or DM_FAILURE.

To retrieve a SMPTE time code string that is stored in a movie track, call mvGetSMPTEStart(), which returns the starting time code as set by mvSetSMPTEStart(). Its function prototype is:

const char* mvGetSMPTEStart( MVid track )

where:

To retrieve the number of frames stored in a track, call mvGetTrackLength(). Its function prototype is:

MVframe mvGetTrackLength ( MVid track )

To determine the track medium, call mvGetTrackMedium(). Its function prototype is:

DMmedium mvGetTrackMedium( MVid track )

mvGetTrackMedium() returns either DM_IMAGE or DM_AUDIO.

mvSetDefaultVol() stores a new value, ranging from 0.0 to 1.0, for the default volume parameter. It returns DM_SUCCESS or DM_FAILURE. Its function prototype is:

int mvSetDefaultVol( MVid audioTrack double volume)

mvGetDefaultVol() returns the default volume setting to use when playing this movie. Its function prototype is:

DMstatus mvGetDefaultVol( MVid audioTrack )

where:

---

Note: The Movie Library currently ignores the default volume setting.

---

The Movie Library supports 8-bit and 16-bit audio samples.

To determine the number of bits used to store each audio sample in an audio track, call mvGetAudioWidth(). Its function prototype is:

int mvGetAudioWidth( MVid audioTrack )

where:

To determine the audio sample rate (in samples per second) for an audio track, call mvGetAudioRate(). Its function prototype is:

double mvGetAudioRate( MVid audioTrack )

where:

To determine the number of audio channels in an audio track, call mvGetAudioChannels(). Its function prototype is:

int mvGetAudioChannels( MVid audioTrack )

mvGetAudioChannels() returns the number of audio channels: 1 for mono; 2 for stereo (the Movie Library does not currently support 4-channel audio tracks).

where:

The Movie Library supports both unsigned and twos complement audio formats that are directly understood by the Audio Library (AL), in particular the ALwritesamps() call, for Silicon Graphics native movie formats.

Audio for QuickTime movies is stored using sampling rates and formats understood by QuickTime on the Apple Macintosh computer. Some of these formats are not directly supported by the AL. See Chapter 31, “Using the Movie Library with QuickTime Movies,” for more information on QuickTime audio.

To determine the format used to store the audio samples in an audio track, call mvGetAudioFormat(). Its function prototype is:

DMaudioformat mvGetAudioFormat( MVid audioTrack )

where:

mvGetAudioFormat() returns either DM_AUDIO_TWOS_COMPLEMENT or DM_AUDIO_UNSIGNED.

To determine the audio compression scheme for an audio track, call mvGetAudioCompression(). Its function prototype is:

const char* mvGetAudioCompression( MVid audioTrack )

where:

Since movies do not currently support audio compression, the only valid value is DM_AUDIO_UNCOMPRESSED.

To change a movie's frame rate by storing a new value for the image rate parameter, call mvSetImageRate(). Its function prototype is:

DMstatus mvSetImageRate( MVid imageTrack,
                         double framesPerSecond )

where:

mvSetImageRate() returns DM_SUCCESS if the image rate was successfully changed; otherwise, it returns DM_FAILURE.

To determine the image rate in frames per second for a movie, call mvGetImageRate(). Its function prototype is:

double mvGetImageRate( MVid imageTrack )

where:

To get the width (x dimension) in pixels of the images stored in an image track, call mvGetImageWidth(). Its function prototype is:

int mvGetImageWidth( MVid imageTrack )

where:

To get the height (y dimension) in pixels of the images stored in an image track, call mvGetImageHeight(). Its function prototype is:

int mvGetImageHeight( MVid imageTrack )

where:

The ordering of scan lines within an image frame depends upon the source of the data. Bottom-to-top is the default data orientation for Movie Library routines. To find out how pixels are ordered, call mvGetImageOrientation(). Its function prototype is:

DMorientation mvGetImageOrientation ( MVid imageTrack)

where:

mvGetImageOrientation() returns the order in which scan lines are stored in the image: DM_BOTTOM_TO_TOP or DM_TOP_TO_BOTTOM.

The Movie Library can read images from and write images to a buffer. You can use the IRIS ImageVision Library to read any of these image formats into a buffer:

The image packing format describes how pixels are packed within images; for example, the word length used to represent the pixel, and the bit order.

Images in a movie file can be stored on disk in any of the image packing formats listed in Table 28-4. When you play a movie whose image track is in a nondefault format, the Movie Library converts the image data to DM_PACKING_RGBX on the fly as it plays the movie.

To get the image packing format for a particular image track, call mvGetImagePacking(). Its function prototype is:

DMpacking mvGetImagePacking( MVid imageTrack )

where:

Table 28-4 lists the image packing formats supported by the Movie Library

Compression settings can result in significant differences in image quality and in playback performance. The most commonly used compression schemes for movies to be played on Silicon Graphics computers are MVC1 and MVC2; QT_VIDEO is frequently used for QuickTime movies to be played on a Macintosh computer.

The Movie Library supports image compression through the Compression Library. The compression methods that have been thoroughly tested with the Movie Library are UNCOMPRESSED, MVC1, MVC2, RLE24, and JPEG. You can also use the QuickTime compression schemes, QT_VIDEO and QT_ANIM, in QuickTime and Silicon Graphics movies if you have purchased and installed the Silicon Graphics QuickTime Compressor Library.

To get the image compression scheme, call mvGetImageCompression(). Its function prototype is:

const char* mvGetImageCompression( MVid imageTrack )

where:

mvGetImageCompression() returns the name of the compression scheme that is used to compress the images.

The most commonly used schemes and the reasons for choosing them are: