mvReadTrackData(3dm)mvReadTrackData(3dm)NAME
mvReadTrackData, mvInsertTrackData, mvInsertTrackDataAtOffset, -
manipulate data in track
SYNOPSIS
#include <dmedia/moviefile.h>
DMstatus mvReadTrackData( MVid track, int index,
size_t bufferSize, void *buffer );
DMstatus mvInsertTrackData( MVid track, MVframes frames, MVtime time,
MVtime duration, MVtimescale timeScale,
size_t bufferSize, void *buffer,
MVdatatype dataType, int paramsId );
DMstatus mvInsertTrackDataAtOffset( MVid track, MVframe frames,
MVtime time, MVtime duration,
MVtimescale timeScale,
off64_t fileOffset, size_t bufferSize,
MVdatatype dataType, int paramsId )
DESCRIPTION
Each instance in track time corresponds to a certain block of physical
data. For example, an image track is made up of bytes that describe
images. The relationship between these two are covered by functions
described in mvTrackData(3dm).
Functions described in this page allow users to have access to such
physical blocks. These are low-level functions that most applications
will not need. They are only useful for applications that need to access
low-level information like file offsets and raw compressed data. They
are analogous to mvReadCompressedImage(3dm) and
mvInsertCompressedImage(3dm), except that they are time based and
medium-neutral.
mvReadTrackData
This function reads a chunk of data out of the file and presents it to
the user.
track id of the track with which the chunk is associated.
dataIndex is the index to the data chunk. An error is set and DM_FAILURE
is returned if this value is out of range. The number of valid data
indices can be retrieved by mvGetTrackNumDataIndex(3dm).
bufferSize is the size of the buffer pointed to by buffer. The size of a
chunk can be retrieved from the function mvGetTrackDataInfo(3dm). An
error is set and DM_FAILURE is returned if this value is smaller than the
Page 1
mvReadTrackData(3dm)mvReadTrackData(3dm)
required size.
buffer is a pointer to the buffer into which the movie library will
write. The user is responsible for the memory management of this buffer.
mvInsertTrackData
This function copies the data in the buffer to the storage file of the
track, and inserts a new segment in the track that corresponds to this
chunk of data.
This function is very similar to mvInsertFramesAtTime, except that the
buffer containing the data will not be processed by the track-specific
code (e.g. compression, color-space conversion, etc), and will be copied
directly in the file. Users who would rather process the data themselves
through other means can use this function.
track the id of the track into which the segment will be inserted.
frames the number of frames contained in the chunk of data to be
inserted.
time the time at which the new segment will be inserted. If the time is
beyond the duration of the track, a gap is first inserted between the
duration of the track and this time.
duration the duration of the new segment to be inserted.
bufferSize is the size of the buffer pointed to by buffer.
buffer contains the buffer which has the data chunk to be copied to the
file.
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
or by default, 0, which is the params as introduced in mvAddTrack, the
first set of parameters contained in a track. If this parameter is out
of range of the valid data params, an error is set and DM_FAILURE is
returned.
mvInsertTrackDataAtOffset
This function is similar to mvInsertTrackData, except that it does not
copy a buffer to a stoage file. Instead it takes a reference to a
storage location (specified by fileOffset and bufferSize) and inserts a
new segment in the track that corresponds to the data chunk that resides
Page 2
mvReadTrackData(3dm)mvReadTrackData(3dm)
there. This allows the user to do their own storage I/O.
track the id of the track into which the segment will be inserted.
frames the number of frames contained in the chunk of data to be
inserted.
time the time at which the new segment will be inserted. If the time is
beyond the duration of the track, a gap is first inserted between the
duration of the track and this time.
duration the duration of the new segment to be inserted.
timescale the timescale of the new segment to be inserted.
fileOffset the location where the data chunk to be added to the track
resides on the storage device.
bufferSize is the size of the buffer pointed to by fileOffset.
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
or by default, 0, which is the params as introduced in mvAddTrack, the
first set of parameters contained in a track. If this parameter is out
of range of the valid data params, an error is set and DM_FAILURE is
returned.
SEE ALSOmvIntro(3dm), mvTrackData(3dm), mvTrackDataParams(3dm), mvAddTrack(3dm).
Page 3
