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 DMSUCCESS
     or DMFAILURE.  For image tracks the image returned in the buffer pointed
     to by buffer are of pixel packing DMIMAGEPACKINGXBGR, interlacing
     DMIMAGENONINTERLACED, and orientation DMIMAGEBOTTOMTOTOP.  For
     audio tracks the audio frames returned in the buffer pointed to by buffer
     are in the format DMAUDIOTWOSCOMPLEMENT.

     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 DMSUCCESS or DMFAILURE.  For image tracks
     mvInsertFrames expects the data pointed to by buffer to be formatted as
     packing DMIMAGEPACKINGXBGR, interlacing DMIMAGENONINTERLACED, and
     orientation DMIMAGEBOTTOMTOTOP.  For audio tracks mvInsertFrames
     expects the data pointed to by buffer to be formatted as
     DMAUDIOTWOSCOMPLEMENT.

     mvAppendFrames takes frameCount frames from buffer and writes them to the
     end of the track.  The value returned is DMSUCCESS or DMFAILURE.  For
     image tracks mvAppendFrames expects the data pointed to by buffer to be
     formatted as packing DMIMAGEPACKINGXBGR, interlacing
     DMIMAGENONINTERLACED, and orientation DMIMAGEBOTTOMTOTOP.  For



                                                                        Page 1

mvEditByFrame(3dm)                                          mvEditByFrame(3dm)



     audio tracks mvAppendFrames expects the data pointed to by buffer to be
     formatted as DMAUDIOTWOSCOMPLEMENT and DMAUDIOBIGENDIAN (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 DMSUCCESS or
     DMFAILURE.

     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 );



                                                                        Page 2

mvEditByFrame(3dm)                                          mvEditByFrame(3dm)




              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