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:
Page 1
mvAddTrack(3dm)mvAddTrack(3dm)
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.
Page 2
mvAddTrack(3dm)mvAddTrack(3dm)
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 */
}
Page 3
mvAddTrack(3dm)mvAddTrack(3dm)
/* 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 ALSOmvIntro(3dm), mvCreate(3dm), mvInsertFramesAtTime(3dm),
mvInsertFrames(3dm), mvSetImageDefaults(3dm), mvQuery(3dm),
mvGetErrno(3dm).
Page 4
