mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)NAMEmvExportFlattenedFile - export a movie to a given file format
SYNOPSIS
#include <dmedia/moviefile.h>
typedef enum __MVmessage
{
MV_BEGIN,
MV_IN_PROGRESS,
MV_END
} MVmessage;
typedef enum __MVoperation
{
MV_COPY_MOVIE_AT_TIME,
MV_COPY_TRACK_AT_TIME,
MV_EXPORT_FLATTENED_FILE
} MVoperation;
typedef DMstatus (*MVprogressfunc)(
MVid movieBeingProcessed,
MVmessage message,
MVoperation operation,
float fraction,
int clientData);
DMstatus mvExportFlattenedFile(
MVid srcMovie,
const char* dstFileName,
DMparams* dstFileFormat,
DMparams* imageFormat,
DMparams* audioFormat,
unsigned int exportFlags,
MVprogressfunc progressCallback,
int progressClientData);
PARAMETERS
srcMovie The movie that contains the content to be exported.
This may be an arbitrarily complex movie, with
multiple image tracks and multiple audio tracks.
dstFileName The pathname of the output file that will be created.
dstFileFormat Specifies what type of file to create (in parameter
MV_FILE_FORMAT), plus any format-specific details.
Valid MV_FILE_FORMATs include MV_FORMAT_QT,
MV_FORMAT_MPEG1, MV_FORMAT_AVI, MV_FORMAT_DIF, and
MV_FORMAT_SGI_3.
Page 1
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
imageFormat The description of the format of the images in the
output file. (See dmSetImageDefaults.) This
parameter can be NULL if no image track is wanted in
the destination file.
audioFormat The description of the format of the audio in the
output file. (See dmSetAudioDefaults.) This
parameter can be NULL if no audio track is wanted in
the destination file.
exportFlags Flags that control when to recompress images, and when
to use gaps. The safest value for this parameter is
zero. Valid flags include MV_EXPORT_USE_GAPS (to
achieve smaller files in some cases),
MV_EXPORT_RECOMP_FEWEST (to avoid recompressing
existing images), MV_EXPORT_RECOMP_CHANGED_Q (to
recompress only when quality settings have changed),
and MV_EXPORT_RECOMP_ALL to force recompression of all
images.
progressCallback This function is called periodically during the
creation of the output movie to report progress.
progressClientData This is passed into the progressCallback function. It
is a convenient hook for clients to store data in.
DESCRIPTION
This function will create a "flattened" movie from any arbitrarily
complex movie. In most cases, the flattened movie will have exactly one
image track and exactly one audio track. In the case of MV_FORMAT_MPEG1
and MV_FORMAT_DIF, a single stream of multiplexed data is created which
adheres to those respective standards. mvExportFlattenedFile will create
the named output file, and do any necessary conversion from the format of
the input movie file.
DM_SUCCESS is returned if the output file was created correctly. If
something goes wrong, DM_FAILURE will be returned and no output file will
be created. If the output file already existed, it may be destroyed even
on failure.
During processing, the progress function pointed at by progressCallback
is called. On the first call, the message is MV_BEGIN. Then there are
multiple MV_IN_PROGRESS calls where fraction (between 0.0 and 1.0)
indicates what fraction of the processing has been completed. On the
last call, the message is set to MV_END.
Page 2
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
If the progress callback returns DM_SUCCESS, the processing will
continue; if it returns DM_FAILURE processing will immediately stop, and
the output file will not be created, and DM_FAILURE will be returned by
the mvExportFlattenedFile call. In this case, mvGetErrno() will be equal
to MV_USER_CANCELLED_PROC upon returning from the mvExportFlattenedFile
call. You can use this functionality to implement a progress dialog with
a cancel button so users can cancel out of long exports.
There are choices about when to recompress images if the input movie and
output file use the same compression scheme; these are controlled by the
bits in exportFlags. If MV_EXPORT_RECOMP_ALL is set, all frames will be
recompressed, no matter what. MV_EXPORT_RECOMP_CHANGED_Q says to
recompress only when the quality settings are different (which allows
better bit-rate control). MV_EXPORT_RECOMP_FEWEST says to never
recompress when the source images use the same compression scheme.
If the MV_EXPORT_USE_GAPS bit is set in exportFlags, gaps will be noted
in the output file, instead of compressing black images. (This is
supported only by the QuickTime file format.)
MOVIE FILES
The file format parameter MV_FILE_FORMAT must be one of: MV_FORMAT_QT,
MV_FORMAT_AVI, MV_FORMAT_MPEG1, MV_FORMAT_DIF, or MV_FORMAT_SGI_3.
The following sections describe the allowed parameter settings for the
different file formats. Any image/audio parameter that is not explicitly
listed must be set to the default value obtained from dmSetImageDefaults
or dmSetAudioDefaults.
QUICKTIME FILES
The file format parameters should just include MV_FORMAT_QT. No other
parameters are supported.
The image format parameters must be set as follows:
DM_IMAGE_WIDTH
Dependent on the DM_IMAGE_COMPRESSION. In most cases this can be
any arbitrary value. Here are some exceptions: for
DM_IMAGE_QT_MJPEGA, and DM_IMAGE_JPEG width must be a multiple of
16. For DM_IMAGE_QT_VIDEO, DM_IMAGE_QT_ANIM, DM_IMAGE_QT_CVID, and
DM_IMAGE_INDEO width must be a multiple of 4.
DM_IMAGE_HEIGHT
Dependent on the DM_IMAGE_COMPRESSION. In most cases this can be
any arbitrary value. Here are some exceptions: For
DM_IMAGE_QT_MJPEGA, and DM_IMAGE_JPEG, height must be a multiple of
Page 3
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
8. For DM_IMAGE_QT_VIDEO, DM_IMAGE_QT_ANIM, DM_IMAGE_QT_CVID, and
DM_IMAGE_INDEO, height must be a multiple of 4.
DM_IMAGE_RATE
Can be almost any value. Some examples include: 29.97, 25.0, 15.0,
and 10.0.
DM_IMAGE_COMPRESSION
Valid settings include DM_IMAGE_UNCOMPRESSED, DM_IMAGE_JPEG,
DM_IMAGE_QT_MJPEGA, DM_IMAGE_DV, DM_IMAGE_DVCPRO, DM_IMAGE_RICE,
DM_IMAGE_QT_VIDEO, DM_IMAGE_QT_ANIM, DM_IMAGE_QT_CVID, and
DM_IMAGE_INDEO.
DM_IMAGE_ORIENTATION
In general, this should be set to DM_IMAGE_TOP_TO_BOTTOM to produce
the most portable QuickTime files. Only specify
DM_IMAGE_BOTTOM_TO_TOP if you are absolutely sure you know what you
are doing.
DM_IMAGE_INTERLACING
In general, this should be set to DM_IMAGE_NONINTERLACED. However,
if the DM_IMAGE_COMPRESSION is set to DM_IMAGE_QT_MJPEGA, it should
be set to DM_IMAGE_INTERLACED_ODD for NTSC size frames, and
DM_IMAGE_INTERLACED_EVEN for PAL size frames. Other compression
types which support interlacing include DM_IMAGE_UNCOMPRESSED and
DM_IMAGE_JPEG.
DM_IMAGE_PACKING
This is highly codec dependent. For DM_IMAGE_QT_MJPEGA and
DM_IMAGE_JPEG, it must be set to DM_IMAGE_PACKING_CbYCrY (4:1:1).
Concerning an image compression of DM_IMAGE_DV or DM_IMAGE_DVCPRO,
it must be set to DM_IMAGE_PACKING_YCrCbYYY (4:1:1) for NTSC DV,
NTSC DVCPRO, and PAL DVCPRO, and DM_IMAGE_PACKING_YCrYYCrYYCbYYCbY
(4:2:0) for PAL DV. See dm_dv(3dm) for a complete discussion on DV
packing issues. For DM_IMAGE_UNCOMPRESSED, packing can be
practically anything, including: DM_IMAGE_PACKING_RGB,
DM_IMAGE_PACKING_RGBX, DM_IMAGE_PACKING_XBGR, DM_IMAGE_PACKING_XRGB,
DM_IMAGE_PACKING_BGRX, DM_IMAGE_PACKING_CbYCr,
DM_IMAGE_PACKING_CbYCrY, and DM_IMAGE_PACKING_CbYCrYYY. For
DM_IMAGE_QT_CVID, packing must be DM_IMAGE_PACKING_CbYCrY, and for
DM_IMAGE_QT_ANIM packing can be one of: DM_IMAGE_PACKING_RGBX,
DM_IMAGE_PACKING_XBGR, DM_IMAGE_PACKING_XRGB, or
DM_IMAGE_PACKING_BGRX.
DM_IMAGE_BITRATE
This is highly codec dependent. Only some codecs support this
parameter. If a codec does support this parameter, it is the number
of bits per second the resulting stream is. Some example values
include: 600,000 (a good bitrate for 4X CDROM drives) and 3,000,000
for disk based playback.
Page 4
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
DM_IMAGE_QUALITY_SPATIAL
This is highly codec dependent. If a codec supports this parameter,
the value of 0.5 allows the codec to use the default spatial
quality.
DM_IMAGE_QUALITY_TEMPORAL
This is highly codec dependent. If a codec supports this parameter,
the value of 0.5 allows the codec to use the default temporal
quality.
DM_IMAGE_KEYFRAME_DISTANCE
If a codec supports this, this is the number of frames between
keyframes.
DM_IMAGE_REFFRAME_DISTANCE.
If a codec supports this, this is the number of frames between
reference frames.
The audio format parameters in audioFormat must be set as follows:
DM_AUDIO_FORMAT
It is recommended to always set this to DM_AUDIO_TWOS_COMPLEMENT.
DM_AUDIO_WIDTH
Can be 8, 16, or 24. A good default is 16.
DM_AUDIO_RATE
This can be almost any value, including 48000, 44100, 32000, 22050,
16000, 11127, and 8000.
DM_AUDIO_CHANNELS
1 for mono, 2 for Stereo.
AVI FILES
The file format parameters should just include MV_FORMAT_AVI. No other
parameters are supported.
The image format parameters must be set as follows:
DM_IMAGE_WIDTH
Dependent on the DM_IMAGE_COMPRESSION. In most cases this can be
any arbitrary value. Here are some exceptions: for DM_IMAGE_JPEG
width must be a multiple of 16.
DM_IMAGE_HEIGHT
Dependent on the DM_IMAGE_COMPRESSION. In most cases this can be
any arbitrary value. Here are some exceptions: For DM_IMAGE_JPEG,
height must be a multiple of 8.
Page 5
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
DM_IMAGE_RATE
Can be almost any value. Some examples include: 29.97, 25.0, 15.0,
and 10.0.
DM_IMAGE_COMPRESSION
Valid settings include DM_IMAGE_UNCOMPRESSED, DM_IMAGE_JPEG,
DM_IMAGE_QT_CVID, and DM_IMAGE_INDEO.
DM_IMAGE_ORIENTATION
In general, this should be set to DM_IMAGE_TOP_TO_BOTTOM to produce
the most portable QuickTime files. Only specify
DM_IMAGE_BOTTOM_TO_TOP if you are absolutely sure you know what you
are doing.
DM_IMAGE_INTERLACING
In general, this should be set to DM_IMAGE_NONINTERLACED. However,
if the DM_IMAGE_COMPRESSION is set to DM_IMAGE_JPEG or
DM_IMAGE_UNCOMPRESSED, it can be set to DM_IMAGE_INTERLACED_ODD for
NTSC size frames, and DM_IMAGE_INTERLACED_EVEN for PAL size frames.
DM_IMAGE_PACKING
This is highly codec dependent. For DM_IMAGE_JPEG, it must be set
to DM_IMAGE_PACKING_CbYCrY (4:1:1). For DM_IMAGE_UNCOMPRESSED,
packing can be practically anything, including:
DM_IMAGE_PACKING_RGB, DM_IMAGE_PACKING_RGBX, DM_IMAGE_PACKING_XBGR,
DM_IMAGE_PACKING_XRGB, DM_IMAGE_PACKING_BGRX,
DM_IMAGE_PACKING_CbYCr, DM_IMAGE_PACKING_CbYCrY, and
DM_IMAGE_PACKING_CbYCrYYY. For DM_IMAGE_QT_CVID, packing must be
DM_IMAGE_PACKING_CbYCrY.
DM_IMAGE_BITRATE
This is highly codec dependent. Only some codecs support this
parameter. If a codec does support this parameter, it is the number
of bits per second the resulting stream is. Some example values
include: 600,000 (a good bitrate for 4X CDROM drives) and 3,000,000
for disk based playback.
DM_IMAGE_QUALITY_SPATIAL
This is highly codec dependent. If a codec supports this parameter,
the value of 0.5 allows the codec to use the default spatial
quality.
DM_IMAGE_QUALITY_TEMPORAL
This is highly codec dependent. If a codec supports this parameter,
the value of 0.5 allows the codec to use the default temporal
quality.
DM_IMAGE_KEYFRAME_DISTANCE
If a codec supports this, this is the number of frames between
keyframes.
Page 6
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
DM_IMAGE_REFFRAME_DISTANCE.
If a codec supports this, this is the number of frames between
reference frames.
The audio format parameters in audioFormat must be set as follows:
DM_AUDIO_FORMAT
It is recommended to always set this to DM_AUDIO_TWOS_COMPLEMENT.
DM_AUDIO_WIDTH
Can be 8, 16, or 24. A good default is 16.
DM_AUDIO_RATE
This can be almost any value, including 48000, 44100, 32000, 22050,
16000, 11127, and 8000.
DM_AUDIO_CHANNELS
1 for mono, 2 for Stereo.
DIF FILES
The file format parameters should just include MV_FORMAT_DIF. No other
parameters are supported.
The image format parameters must be set as follows:
DM_IMAGE_WIDTH must be 720
DM_IMAGE_HEIGHT
must be 480 for NTSC; 576 for PAL
DM_IMAGE_RATE
must be 29.97 for NTSC; 25.0 for PAL
DM_IMAGE_COMPRESSION
must be either DM_IMAGE_DV or DM_IMAGE_DVCPRO
DM_IMAGE_ORIENTATION
DM_IMAGE_TOP_TO_BOTTOM
DM_IMAGE_INTERLACING
DM_IMAGE_NONINTERLACED
DM_IMAGE_ARRANGEMENT
DM_IMAGE_FULL_FRAME
Page 7
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
DM_IMAGE_PACKING
DM_IMAGE_PACKING_YCrCbYYY (4:1:1) for NTSC DV, NTSC DVCPRO, and PAL
DVCPRO, and DM_IMAGE_PACKING_YCrYYCrYYCbYYCbY (4:2:0) for PAL DV.
See dm_dv(3dm) for a complete discussion on the DIF file format and
packing issues.
The parameters that control quality and compression ratio are all ignored
for DV: DM_IMAGE_BITRATE, DM_IMAGE_QUALITY_SPATIAL,
DM_IMAGE_QUALITY_TEMPORAL, DM_IMAGE_KEYFRAME_DISTANCE, and
DM_IMAGE_REFFRAME_DISTANCE.
The audio format parameters in audioFormat must be set as follows:
DM_AUDIO_FORMAT
DM_AUDIO_TWOS_COMPLEMENT
DM_AUDIO_WIDTH
16
DM_AUDIO_RATE
48000, 44100, or 32000. If the image compression is
DM_IMAGE_DVCPRO, then only 48000 is allowed.
DM_AUDIO_CHANNELS
1 for mono, 2 for Stereo. If the image compression is
DM_IMAGE_DVCPRO, then only Stereo is allowed.
DM_AUDIO_COMPRESSION
DM_AUDIO_DV
MPEG-1 FILES
The file format parameters should just include MV_FORMAT_MPEG1. No other
parameters are supported.
The image format parameters must be set as follows:
DM_IMAGE_WIDTH Must be a multiple of 16.
DM_IMAGE_HEIGHT
Must be a multiple of 16
DM_IMAGE_RATE
Must be one of: 60.0, 59.94, 50.0, 30.0, 29.97, 25.0, 24.0, 23.976.
Page 8
mvExportFlattenedFile(3dm)mvExportFlattenedFile(3dm)
DM_IMAGE_COMPRESSION
Must be DM_IMAGE_MPEG1
DM_IMAGE_ORIENTATION
Must be DM_IMAGE_TOP_TO_BOTTOM
DM_IMAGE_PACKING
Must be DM_IMAGE_PACKING_CbYCrYYY (4:2:0).
DM_IMAGE_BITRATE
The number of bits per second the resulting stream is. Some example
values include: 600,000 (a good bitrate for 4X CDROM drives) and
3,000,000 for disk based playback.
DM_IMAGE_QUALITY_SPATIAL
The value of 0.5 allows the codec to use the default spatial
quality.
DM_IMAGE_QUALITY_TEMPORAL
The value of 0.5 allows the codec to use the default temporal
quality.
DM_IMAGE_KEYFRAME_DISTANCE
The number of frames between keyframes.
DM_IMAGE_REFFRAME_DISTANCE.
The number of frames between reference frames.
The audio format parameters in audioFormat must be set as follows:
DM_AUDIO_FORMAT
DM_AUDIO_TWOS_COMPLEMENT
DM_AUDIO_WIDTH
Must be 16.
DM_AUDIO_RATE
48000, 44100, or 32000.
DM_AUDIO_CHANNELS
1 for mono, 2 for Stereo.
SEE ALSOmvIntro(3dm), dm_dv(3dm), dmSetImageDefaults(3dm),
dmSetAudioDefaults(3dm).
Page 9
