mvAddTrack(3dm) mvAddTrack(3dm) NAME mvAddTrack, mvRemoveTrack - add or remove tracks in a movie SYNOPSIS #include <dmedia/moviefile.h> DMstatus mvAddTrack( MVid movie, DMmedium medium, DMparams* params, DMparams* paramsSetOrNULL, MVid* returnTrack ) DMstatus mvRemoveTrack( MVid movie, MVid track ) DESCRIPTION A movie contains a number of separate, parallel tracks, each of which contains one type of data. A movie may contain any number of tracks. These functions are used to add tracks to newly created movies, remove tracks from existing movies, and find tracks in an existing movie. The type MVid is used both for movies and for tracks so that the generic tag functions (see mvParams(3dm)) can work on movies and tracks. mvAddTrack adds a new track to a movie and returns the MVid for that track. The medium parameter determines the type of track. For image (type DM_IMAGE) tracks the parameters used to configure the track (params) should be set up by calling mvSetImageDefaults. For audio (type DM_AUDIO) tracks, the parameters used to configure the track (params) should be set up by calling mvSetAudioDefaults. The parameters actually used in the track are stored into paramsSetOrNULL if it is not NULL. The new track, if created successfully, is returned in returnTrack. DM_SUCCESS or DM_FAILURE is returned. mvRemoveTrack removes a track from a movie. DM_SUCCESS or DM_FAILURE is returned. IMAGE COMPRESSION The DM_IMAGE_COMPRESSION parameter that is given when creating an image track specifies the default compression scheme used when storing the movie. Different settings can result in large differences in image quality and in playback performance. The compression types currently supported for SGI movies are: UNCOMPRESSED, MVC1, MVC2, RLE, RLE24, and JPEG. The compression types currently supported for QuickTime movies are: UNCOMPRESSED, QT_VIDEO, QT_ANIM, QT_CVID, MVC1, MVC2, RLE, RLE24, JPEG, and INDEO. The compression types currently supported for AVI movies are: UNCOMPRESSED, QT_CVID, JPEG, and INDEO. QT_CVID (Cinepak) and INDEO can only be used to create tracks on machines that have a Cinepak/Indeo Encoder License. The most commonly used schemes and the reasons for choosing them are: UNCOMPRESSED: Uncompressed images are, of course, very large, but there is no loss of image quality. For the best quality in a final movie, all image manipulation and storage should be with uncompressed images until the final movie is produced, at which time the images can be compressed. MVC1: This is a good general-purpose compression scheme. It is a color cell compression technique that works well for video, but can cause fuzzy edges in high-contrast animation. MVC2: This is another good general-purpose compression scheme. It is similar to MVC1, but achieves greater compression at the cost of a longer compression time. Decompression is faster than for MVC1. RLE24: This is a lossless compression that uses run-length encoding. It is good for animation where there are large areas that have identical colors. JPEG: JPEG is good for video, but is slow. QT_VIDEO: This is the compression used for QuickTime movies that contain video. Like MVC1, QT_VIDEO is a color cell compression technique. It includes temporal compression and is good for video and reasonable for animation. QT_ANIM: This is a lossy run-length encoding scheme used for QuickTime movies. It also includes temporal compression. It has excellent compression ratios for animation that has large areas of similar colors. QT_CVID: This is a lossy compression scheme that achieves higher compression ratios and faster playback than QT_VIDEO. With this compression scheme decompression is much faster than compression, so it's best used on movies that will be compressed once and played back many times. INDEO: This is a lossy compression scheme that can be used in AVI and QuickTime movies. The most commonly used compression scheme for movies to be played on SGI machines is MVC1. For QuickTime movies to be played on a Macintosh, QT_VIDEO and QT_CVID are frequently used. The most frequently used compression schemes in AVI movies are QT_CVID and INDEO. Four optional parameters may be set to allow more control over the image compression of created tracks. These parameters are: DM_IMAGE_QUALITY_SPATIAL: This parameter may be used to control the spatial quality for compressors that use a spatial quality factor such as JPEG and the QuickTime compressors. The value of DM_IMAGE_QUALITY_SPATIAL must be a double between 0 and 1.0 where 0 is minimum quality and 1.0 is maximum quality. If this parameter is not set the default value of this parameter will be set to .75 for JPEG files and .5 for the QuickTime compressors. DM_IMAGE_QUALITY_TEMPORAL: This parameter may be used to control the temporal quality for compressors that take a temporal quality factor such as QuickTime Video and QuickTime Animation. The value of DM_IMAGE_QUALITY_TEMPORAL must be a double between 0 and 1.0 where 0 is minimum quality and 1.0 is maxiumum quality. If this parameter is not set the default value of this parameter is set to .5 for the QuickTime compressors. DM_IMAGE_BITRATE: This parameter may be used to control the bitrate of the compressed image track with the Cinepak compressor. The value of DM_IMAGE_BITRATE must be an integer greater than 0 whose value specifies the number of bits/second of compressed data in the image track. This value is only used on compression of the data and is not stored in the movie file. DM_IMAGE_KEYFRAME_DISTANCE: This parameter may be used to control the frequency of keyframes in the image track when used with a compressor that uses keyframes such as the QuickTime compressors. DM_IMAGE_KEYFRAME_DISTANCE must be an integer greater than 0. The default value of DM_IMAGE_KEYFRAME_DISTANCE is 5. This value is only used on compression of the data and is not stored in the movie file. EXAMPLE #include <dmedia/moviefile.h> void AddAudioTrack( MVid movie ) { DMparams* audioParams; MVid audioTrack; if ( dmParamsCreate( &audioParams ) != DM_SUCCESS ) { /* handle error */ } if ( mvSetAudioDefaults( audioParams, 8, /* bits/sample */ 22050, /* sample rate */ 1, /* number of channels */ MV_FORMAT_QT /* file format */ ) != DM_SUCCESS ) { /* handle error */ } if ( mvAddTrack( movie, DM_AUDIO, audioParams, NULL, &audioTrack ) != DM_SUCCESS ) { /* handle error */ } /* Write audio data to track */ /* with mvInsertFrames(3dm) */ } CAVEATS For multi-platform compatibility, uncompressed QuickTime movies created with DM_IMAGE_PACKING set to DM_IMAGE_PACKING_XRGB will actually be stored as DM_IMAGE_PACKING_ARGB. If uncompressed QuickTime movies are created with DM_IMAGE_ORIENTATION set to DM_IMAGE_BOTTOM_TO_TOP, the movie may not be readable on non-SGI platforms. SEE ALSO mvIntro(3dm), mvCreate(3dm), mvInsertFramesAtTime(3dm), mvInsertFrames(3dm), mvSetImageDefaults(3dm), mvQuery(3dm), mvGetErrno(3dm). Page 4