mvReadTrackDataFields(3dm)

NAME
     mvReadTrackDataFields, mvInsertTrackDataFields - read and insert field
     based data


SYNOPSIS
     #include <dmedia/moviefile.h>


     DMstatus mvReadTrackDataFields( MVid track, int index,
                               size_t sizeFirstField, void *bufFirstField,
                               size_t sizeSecondField, void *bufSecondField );

     DMstatus mvInsertTrackDataFields( MVid track,
                              MVtime time, MVduration duration,
                              MVtimescale timeScale,
                              size_t sizeFirstField, void *bufFirstField,
                              size_t sizeSecondField, void *bufSecondField,
                              MVdatatype datatype, int paramsId );

DESCRIPTION
     The data to describe a single image in an image track may be made up of
     two fields.  In a QuickTime file, an auxillary table can be stored in the
     meta data area to describe the sizes and relative positions of these
     fields.  When field information is available, mvReadTrackDataFields can
     be used to read each field into its own buffer.  mvInsertTrackDataFields
     may be used to insert field data in separate buffers into a track.  This
     feature is only fully supported for QuickTime files.

     mvReadTrackDataFields

     This function fetches a data chunk and reads the data into the 2 buffers,
     one field in each buffer.  The function must be called with a valid track
     in track.  sizeFirstField should contain the size of the buffer pointed
     to by bufFirstfield.  sizeSecondField should contain the size of the
     buffer pointed to by bufSecondField.

     If the function succeeds, DM_SUCCESS is returned and:

     bufFirstField will contain the bytes corresponding to the first field of
     the data chunk

     bufSecondField will contain the bytes corresponding to the second field
     of the data chunk

     The function can fail under the following circumstances:

     1. track id is invalid (error code: MV_BAD_ID) 2. index is out of range
     (error code: MV_PARAM_OUT_OF_RANGE) 3. if the data is not of image type
     or is not interlaced. (error code:  MV_INVALID_DATA_TYPE) 4. the track
     data cannot be parsed as 2 separate fields (error code:
     MV_INFO_NOT_AVAILABLE) 5. the sizes of the buffers are not big enough to
     hold the data (error code: MV_BUFFER_TOO_SMALL)

     mvInsertTrackDataFields

     This function inserts 2 fields of data into a track for a given time and
     duration.

     The function must be callsed with a valid track.  The other parameters
     are interpreted as follows:

     time is the time at which the new segment is to be inserted.  If the time
     specified is beyond the duration of the track, an empty segment will
     first be inserted to cover the time between the duration of the track and
     the time specified.

     duration is the duration for which the inserted segment is to last.

     timescale is the timescale for time and duration.

     sizeFirstField contains the size of valid data pointed to by
     bufFirstField.

     bufFirstField contains the bytes corresponding to the first field to be
     inserted into the movie file.  The data must be of the same format
     described by the parameters indexed by paramsId.

     sizeSecondField contains the size of valid data pointed to by
     bufSecondField.

     bufSecondField contains the bytes corresponding to the second field to be
     inserted into the movie file.  The data must be of the same format
     described by the parameters indexed by paramsId.

     dataType contains the datatype of the chunk that is being passed in.
     Currently, this bit mask is only used to indicate whether the chunk is a
     key frame or not, and valid types are MV_FRAMETYPE_DELTA (for delta
     frames) and MV_FRAMETYPE_KEY (for key frames).  All uncompressed frames
     or compressed frames from a compression scheme that is not key-frame
     based are considered key frames.

     paramsId is the index of the parameter returned by mvAddTrackDataParams.
     The default index is 0, which is the index of the params introduced by
     mvAddTrack.  If this parameter is out of range of the valid data params,
     an error is set and DM_FAILURE is returned.  The field
     DM_IMAGE_INTERLACING in the DMparams pointed to by paramsId must one of
     DM_IMAGE_INTERLACED_ODD or DM_IMAGE_INTERLACED_EVEN.


SEE ALSO
     mvGetTrackDataFieldInfo(3dm), mvSetTrackDataFieldInfo(3dm),
     mvTrackDataHasFieldInfo(3dm), mvReadTrackData(3dm),
     mvInsertTrackData(3dm).