mvExportFlattenedFile(3dm) mvExportFlattenedFile(3dm) NAME mvExportFlattenedFile - 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. 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. 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 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. 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. 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. 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 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. 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 ALSO mvIntro(3dm), dm_dv(3dm), dmSetImageDefaults(3dm), dmSetAudioDefaults(3dm). Page 9