mvEditByFrame(3dm)                                          mvEditByFrame(3dm)


NAME
     mvEditByFrame:  mvReadFrames, mvInsertFrames, mvAppendFrames,
     mvDeleteFrames, mvPasteFrames - edit/manipulate a movie track


SYNOPSIS
     #include <dmedia/moviefile.h>


     DMstatus mvReadFrames( MVid track, MVframe frameIndex,
                         MVframe frameCount, size_t bufferSize,
                         void* buffer );

     DMstatus mvInsertFrames( MVid track, MVframe frameIndex,
                         MVframe frameCount, size_t bufferSize,
                         void* buffer );

     DMstatus mvAppendFrames( MVid track, MVframe frameCount,
                         size_t bufferSize, void* buffer );

     DMstatus mvDeleteFrames( MVid track, MVframe frameIndex,
                         MVframe frameCount );

     DMstatus mvPasteFrames( MVid fromTrack, MVframe fromFrameIndex,
                         MVframe frameCount, MVid toTrack,
                         MVframe toFrameIndex );


DESCRIPTION
     mvReadFrames reads frameCount frames from the track, starting with
     frameIndex, and places them in buffer.  The value returned is DM_SUCCESS
     or DM_FAILURE.  For image tracks the image returned in the buffer pointed
     to by buffer are of pixel packing DM_IMAGE_PACKING_XBGR, interlacing
     DM_IMAGE_NONINTERLACED, and orientation DM_IMAGE_BOTTOM_TO_TOP.  For
     audio tracks the audio frames returned in the buffer pointed to by buffer
     are in the format DM_AUDIO_TWOS_COMPLEMENT for all integer formats,
     DM_AUDIO_FLOAT for 32-bit floating point format, or DM_AUDIO_DOUBLE for
     64-bit floating point format.

     mvInsertFrames takes frameCount frames from buffer and writes them to the
     track, starting at frameIndex.  The previous contents of the track from
     frameIndex on are shifted by frameCount to make room for the new frames.
     The value returned is DM_SUCCESS or DM_FAILURE.  For image tracks
     mvInsertFrames expects the data pointed to by buffer to be formatted as
     packing DM_IMAGE_PACKING_XBGR, interlacing DM_IMAGE_NONINTERLACED, and
     orientation DM_IMAGE_BOTTOM_TO_TOP.  For audio tracks mvInsertFrames
     expects the data pointed to by buffer to be formatted as
     DM_AUDIO_TWOS_COMPLEMENT for all integer formats, DM_AUDIO_FLOAT for 32-
     bit floating point format, or DM_AUDIO_DOUBLE for 64-bit floating point
     format.

     mvAppendFrames takes frameCount frames from buffer and writes them to the


     end of the track.  The value returned is DM_SUCCESS or DM_FAILURE.  For
     image tracks mvAppendFrames expects the data pointed to by buffer to be
     formatted as packing DM_IMAGE_PACKING_XBGR, interlacing
     DM_IMAGE_NONINTERLACED, and orientation DM_IMAGE_BOTTOM_TO_TOP.  For
     audio tracks mvAppendFrames expects the data pointed to by buffer to be
     formatted as DM_AUDIO_TWOS_COMPLEMENT and DM_AUDIO_BIG_ENDIAN (if the
     audio is more than 8 bits per sample). Some movies cannot be read or
     edited while appending; see mvIsAppendOnly(3dm).

     mvDeleteFrames removes frameCount frames from the track, starting at
     frameIndex.  Any subsequent frames are shifted back into the empty space,
     making the track shorter.  The value returned is DM_SUCCESS or
     DM_FAILURE.

     mvPasteFrames is provided for convenience and efficiency.  It is
     equivalent to reading frames from one track and inserting them into
     another track, but is much more efficient.  The example below is
     equivalent, assuming that a large enough buffer can be allocated:


          DMstatus mvPasteFrames( MVid    fromTrack,
                                  MVframe fromFrameIndex,
                                  MVframe frameCount,
                                  MVid    toTrack,
                                  MVframe toFrameIndex )
          {
              size_t    size;
              void*     buffer;
              DMparams* params = mvGetParams( fromTrack );

              switch ( mvGetTrackMedium( fromTrack ) ) {
                  case DM_IMAGE:
                  /* mvReadFrames on image tracks always returns xbgr,
                        bottom to top, non interlaced data */
                     dmParamsSetEnum( params,
                                      DM_IMAGE_PACKING,
                                      DM_IMAGE_PACKING_XBGR );
                     dmParamsSetEnum( params,
                                      DM_IMAGE_INTERLACING,
                                      DM_IMAGE_NONINTERLACED );
                     dmParamsSetEnum( params,
                                      DM_IMAGE_ORIENTATION,
                                      DM_IMAGE_BOTTOM_TO_TOP );
                     size = dmImageFrameSize(params);
                     break;
                  case DM_AUDIO:
                  /* mvReadFrames on audio tracks always returns
                        twos complement audio data */
                     dmParamsSetEnum( params,
                                      DM_AUDIO_FORMAT,
                                      DM_AUDIO_TWOS_COMPLEMENT );
                     size = dmAudioFrameSize(params);


                     break;
              }

              buffer = malloc( size * frameCount );

              if ( mvReadFrames( fromTrack,
                                 fromFrameIndex,
                                 frameCount,
                                 size * frameCount,
                                 buffer ) != DM_SUCCESS )
                  return DM_FAILURE;

              if ( mvInsertFrames( toTrack,
                                   toFrameIndex,
                                   frameCount,
                                   size * frameCount,
                                   buffer ) != DM_SUCCESS )
                  return DM_FAILURE;

              return DM_SUCCESS;
          }


SEE ALSO
     mvIntro(3dm), mvIsAppendOnly(3dm), mvAddTrack(3dm), mvGetAudioWidth(3dm),
     mvGetImageWidth(3dm), mvGetErrno(3dm), mvTrackData(3dm).


                                                                        Page 3