[ Previous | Next | Contents | Glossary | Home | Search ]
Ultimedia Services Version 2 for AIX: Programmer's Guide and Reference

UMSAVIReadWrite Object

The AVI file read/write object provides methods to access, read, write, and parse files in the AVI format. In this section, the term track refers to what the AVI format calls a stream.

When writing to a file, this object adds index entries if the file has an index. When creating a new file, the AVIF_HASINDEX bit in the dwFlags field of the MainAVIHeader structure can be set to tell this object to create an index. If this bit is not set, this object does not create an index.

If an index is present in the file, it is always used by this object. If the file does not have an index, seek operations are still possible but with reduced performance. The object goes to frame 0 and steps through the frames until it reaches the target frame.

When writing to a file, this object always creates rec chunks to hold the data. When reading from a file, this object accepts data with or without rec chunks.

The frame numbering starts at 0. If there are 60 frames in the file, they are numbered from 0 to 59. The rec chunks are considered one frame; all the subchunks of a rec chunk are considered to be in the same frame.

If each rec chunk (R) has one audio (A) subchunks and one video (V) subchunk, the frame numbering is as follows:

 R{A V}   R{A V}  R{A V}  R{A V}  R{A V}  R{A V} ...
|0       |1      |2      |3      |4      |5     |...

If each rec chunk (R) has two audio (A) and one video (V) subchunk, the frame numbering is as follows:

 R{A A V}   R{A A V}  R{A A V}  R{A A V}  R{A A V}  R{A A V} ...
|0         |1        |2        |3        |4        |5             |...

If one track has initial frames, the numbering is as follows (dwInitialFrames is equal to 2, dwTotalFrames is equal to 8):

 R{A} R{A} R{A V} R{A V} R{A V} R{A V} R{A V} R{A V} R{V}  R{V}
|0   |1   |2     |3     |4     |5     |6     |7     |8    |9

If no rec chunks are used, the frame numbering is as follows:

 A V    A V     A V    A V     A V      A V ...
|0     |1      |2      |3      |4      |5    |...

If no rec chunks are used and one track has initial frames, the numbering is as follows: (dwInitialFrames is equal to 2, dwTotalFrames is equal to 8)

 A   A   A V  A V  A V  A V  A V  A V  V  V
|0  |1  |2   |3   |4   |5  |6   |7   |8  |9

If no rec chunks are used and there are two audio chunks for every video chunk, the frame numbering is as follows:

 A   A V A   A V A   A V A   A V A   A V
|0  |1  |2  |3  |4  |5 |6  |7  |8   |9

To learn more about the UMSAVIReadWrite object, see:

For introductory information, see Formatted File Access Objects.

AVI File Format

The AVI file format is built on top of the RIFF file format. The following is a description of the AVI file format.

RIFF ( 'AVI'
        LIST ( 'hdrl'
                'avih' ( <Main AVI Header> )
                LIST ( 'strl'
                        'strh' ( <Stream 1 Header> )
                        'strf' ( <Stream 1 Format> )
                        ['strd' ( <Stream 1 optional codec data> )]
                )
                LIST ( 'strl'
                        'strh' ( <Stream 2 Header> )
                        'strf' ( <Stream 2 Format> )
                        ['strd' ( <Stream 2 optional codec data> )]
                )
                ...
        )
        LIST ( 'movi'
                {
                        '##dc' ( <compressed DIB> )
                        |
                        LIST ( 'rec '
                                '##dc' ( <compressed DIB> )
                                '##db' ( <uncompressed DIB> )
                                '##wb' ( <audio data> )
                                '##pc' ( <palette change> )
                                ...
                        )
                }
                ...
        )
        [ 'idx1' ( <AVI Index> ) ]
)

Where ## is the track number. For example, if video was track 0 and audio was track 1, the video chunks would be '00dc' and the audio chunks would be '01wb'.

Type Definitions

The object defines the following data types in the avistructs.h file in the:

typedef signed char sint1;
typedef unsigned char uint1;
typedef signed short sint2;
typedef unsigned short uint2;
typedef signed long sint4;
typedef unsigned long uint4;

Additionally the following AVI file structures are defined:

typedef struct {
    uint4 dwMicroSecPerFrame;
    uint4 dwMaxBytesPerSec;
    uint4 dwReserved1;
    uint4 dwFlags;
    uint4 dwTotalFrames;
    uint4 dwInitialFrames;
    uint4 dwStreams;
    uint4 dwSuggestedBufferSize;
    uint4 dwWidth;
    uint4 dwHeight;
    uint4 dwScale;
    uint4 dwRate;
    uint4 dwStart;
    uint4 dwLength;
} MainAVIHeader;
typedef struct {
    uint4 fccType;
    uint4 fccHandler;
    uint4 dwFlags;
    uint4 dwReserved1;
    uint4 dwInitialFrames;
    uint4 dwScale;
    uint4 dwRate;
    uint4 dwStart;
    uint4 dwLength;
    uint4 dwSuggestedBufferSize;
    uint4 dwQuality;
    uint4 dwSampleSize;
} AVIStreamHeader;
typedef struct {
    uint1 bFirstEntry;
    uint1 bNumEntries;
    uint2 wFlags;
} AVIPALCHANGE;
typedef struct {
    uint4 ckid;
    uint4 dwFlags;
    uint4 dwChunkOffset;
    uint4 dwChunkLength;
} AVIINDEXENTRY;

Enumeration Lists

To avoid name collision on defines, integer values have been captured as enumerated lists. The set of valid values from an enumerated list can vary with the application. The detailed method descriptions describe the valid or possible values for the specific use. The enumerated lists that are defined for this object are:

enum ReturnCode {
   Success, 
   Failure, 
   FileNotOpen, 
   InvalidTrack, 
   StorageAllocationFailure, 
   InvalidArgument, 
   NotAnAVIFile, 
   RiffFailure, 
   EndOfFile 
   };

Method Descriptions

ReturnCode close()

Description

This function flushes buffers and closes the file. This can be called by the destructor if needed.

Return Values
Success
Failure

ReturnCode flush()

Description

This method flushes data held in the object to the file.

Return Values
Success
Failure
RiffFailure

ReturnCode get_audio_chunk(in void *v)

Description

This returns the next audio chunk from the AVI file. The chunks are returned in the order they exist in the file. If track selection is used, only the selected tracks are returned. The default is that all tracks are selected. This function skips past any video chunks to get the next audio chunk.

This method identifies an audio chunk by checking the stream header field fccType to see if it is equal to FOURCC_auds. This method does not recognize an audio chunk if it is not marked as type auds.

Arguments
in void *v This returns the next audio chunk from the AVI file. The caller should supply enough space for the chunk.
Return Values
Success
Failure
FileNotOpen
InvalidArgument
EndOfFile

long get_audio_chunk_size()

Description

This returns the size of the next audio chunk from the AVI file. The sizes of the chunks are returned in the order they exist in the file. If track selection is used, only the sizes of chunks from the selected tracks are returned. The default is that all tracks are selected. This function skips past any video chunks to get at the next audio chunk.

This method identifies an audio chunk by checking the stream header field fccType to see if it is equal to FOURCC_auds. This method does not recognize an audio chunk if it is not marked as type auds.

After this method is called, the get_chunk_fourcc, get_chunk_track, and get_chunk_flags methods apply to the next audio chunk to be read from the file with the get_audio_chunk method. Before this method is called, those three methods can return information about some previous chunk.

Return Values

The return value is the size in bytes of the next audio chunk. A size of 0 indicates end of file. A size of -1 indicates an error.

ReturnCode get_avi_header(in void *headerp)

Description

This returns the MainAVIHeader structure from the AVI file. All byte-order swapping has been done.

Arguments
in void *headerp This should be a pointer to a MainAVIHeader structure.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

ReturnCode get_chunk(in void *v)

Description

This method returns the next video or audio chunk from the AVI file. The type of the chunk can be determined from the track number. The tracks are returned in the order they exist in the file. If track selection is used, only the selected tracks are returned. The default is that all tracks are selected.

Arguments
in void *v This returns the next video or audio chunk from the AVI file. The caller must supply enough space to hold the chunk.
Return Values
Success
Failure
FileNotOpen
InvalidArgument
EndOfFile

long get_chunk_flags()

Description

This method returns the value of the dwFlags field in the AVIINDEXENTRY structure for the chunk. This method applies to the next chunk to be read from the file.

Return Values

Possible values are -1 in case of an error, 0 in case there is no index in the file, or the value of the dwFlags field.

long get_chunk_fourcc()

Description

This method returns the RIFF FOURCC value of the chunk containing the audio or video data. This method applies to the next chunk to be read from the file.

Return Values

Possible values are 0 if not successful or the RIFF FOURCC value of the chunk containing the current chunk.

long get_chunk_size()

Description

This method gets the size of the next video or audio chunk in the AVI file. Unselected tracks are bypassed by this method. This method applies to the next chunk to be read from the file. After this method is called, the get_chunk_fourcc, get_chunk_track, and get_chunk_flags methods apply to the next chunk to be read from the file.

Return Values

If successful, returns the size in bytes of the next chunk. A 0 is returned if at the end of file. A -1 is returned if unsuccessful.

long get_chunk_track()

Description

This method returns the track number for the chunk. This method applies to the next chunk to be read from the file.

Return Values

Possible return values are -1 if not successful or the track number for the current chunk.

ReturnCode get_current_frame_number(in long *frame_number)

Description

This function returns the frame number for the next frame to be read. Frame numbers start at 0. A file with 10 frames has frame numbers 0 to 9. This method applies to the next chunk to be read from the file.

Arguments
in long *frame_number This is a pointer to a long integer for the next frame to be read.
Return Values
Success
Failure
InvalidArgument
FileNotOpen

ReturnCode get_index(in void *v)

Description

This method gets a copy of the index from the file (if it exists). The caller must supply enough space to hold all the AVIINDEXENTRY structures in the index. The caller can use get_index_size to find out how many structures are needed.

Arguments
in void *v This is a pointer to an array of AVIINDEXENTRY structures.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

long get_index_size()

Description

This method returns the number of AVIINDEXENTRY structures in the file.

Return Values

The return value is 0 if there is no index in the file or if there are no chunks in the file. Otherwise, it returns the number of AVIINDEXENTRY structures in the file.

ReturnCode get_strd_data(in long count, in void *datap)

Description

This function returns the strd data chunks from the AVI file. This data chunk is optional. There may be one for each track. If the size that is returned by the get_strd_sizes method is 0, that track does not have a strd chunk. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure. To find the sizes of each strd chunk, use the get_strd_sizes method. Byte-order swapping has not been done.

Arguments
in long count This is the number of buffers pointed to by datap.
in void *datap This is a pointer to an array of count pointers to buffers to hold the strd data.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

ReturnCode get_strd_sizes(in long count, in long *sizep)

Description

This method returns the sizes of each strd data chunk from the AVI file. This data chunk is optional. There may be one for each track. If the size that is returned is 0, that track does not have a strd chunk. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure.

Arguments
in long count This is the number of long integers pointed to by sizep.
in long *sizep This should be a pointer to count long integers.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

ReturnCode get_stream_headers(in long count, in void *headerp)

Description

This returns the AVIStreamHeader structures from the AVI file. There should be one for each track. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure. All byte-order swapping has been done.

Arguments
in long count This is the number of AVIStreamHeader structures pointed to by headerp.
in void *headerp This should be a pointer to count AVIStreamHeader structures.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

ReturnCode get_strf_data(in long count, in void *datap)

Description

This function returns the strf data chunks from the AVI file. There should be one for each track. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure. To find the sizes of each strf chunk, use the get_strf_sizes method. Byte-order swapping has not been done.

Arguments
in long count This is the number of buffers pointed to by datap.
in void *datap This is a pointer to an array of count pointers to buffers to hold the strf data.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

ReturnCode get_strf_sizes(in long count, in long *sizep)

Description

This method returns the sizes of each strf data chunk from the AVI file. There should be one for each track. To find the value of count, use the get_track_count method or use the dwStreams value from the MainAVIHeader structure.

Arguments
in long count This is the number of long integers pointed to by sizep.
in long *sizep This should be a pointer to count long integers.
Return Values
Success
Failure
FileNotOpen
InvalidArgument

long get_track_count();

Description

This returns the number of tracks in the file.

Return Values

This returns the number of tracks in the file. A 0 is returned in case of an error.

ReturnCode get_video_chunk(in void *v)

Description

This returns the next video chunk from the AVI file. The chunks are returned in the order they exist in the file. If track selection is used, only the selected tracks are returned. The default is that all tracks are selected. This function skips past any audio chunks to get at the next video chunk.

This method identifies a video chunk by checking the stream header field fccType to see if it is equal to FOURCC_vids. This method does not recognize a video chunk if it is not marked as type vids.

Arguments
in void *v This returns the next video chunk from the AVI file. The caller should supply enough space to hold the chunk.
Return Values
Success
Failure
FileNotOpen
InvalidArgument
EndOfFile

long get_video_chunk_size()

Description

This returns the size of the next video chunk from the AVI file. The sizes of the chunks are returned in the order they exist in the file. If track selection is used, only the sizes of chunks from the selected tracks are returned. The default is that all tracks are selected. This function skips past any audio chunks to get at the next video chunk.

This method identifies a video chunk by checking the stream header field fccType to see if it is equal to FOURCC_vids. This method does not recognize a video chunk if it is not marked as type vids.

After this method is called, the get_chunk_fourcc, get_chunk_track, and get_chunk_flags methods apply to the next video chunk to be read from the file with the get_video_chunk method. Before this method is called, those three methods can return information about some previous chunk.

Return Values

The return value is the size in bytes of the next video chunk. A size of 0 indicates end of file. A size of -1 indicates an error.

ReturnCode open(in string path, in long oflag, in long filemode)

Description

This function opens an AVI file for reading or writing.

Arguments
in string *path This is the path name of the Ultimotion Matinee file to be opened.
in long oflag This is the bit-wise OR of the flags from the fcntl.h file used in the same way they are used for the libc open function.
in long filemode This integer is the permissions mode for the file being created. This value is ignored if the file already exists. It is used in the same way as for the libc open function.
Return Values
Success
Failure
InvalidArgument
NotAnAVIFile
RiffFailure

ReturnCode put_avi_header(in void *headerp)

Description

This method writes the MainAVIHeader to the file. Most of the fields in the structure should be filled by the caller. The rest are calculated or overridden by this method. Some consistency checks are applied to the values filled by the caller. This header can be rewritten at any time. The object gets better performance and uses less temporary space if the header is written before writing frames.

Set the following field values in the structure:

 dwMicroSecPerFrame
 dwMaxBytesPerSec
 dwReserved1 (set to zero)
 dwFlags
 dwInitialFrames
 dwStreams
 dwSuggestedBufferSize
 dwWidth
 dwHeight
 dwScale
 dwRate
 dwStart
 dwLength

The dwStreams value is checked and AVIStreamHeader stream headers are deleted or created to match.

If the dwFlags value has the AVIF_HASINDEX bit set but there is no index in the file, an index is created. If the dwFlags value has the AVIF_MUSTUSEINDEX bit set but does not have the AVIF_HASINDEX bit set, the method returns an error.

The dwTotalFrames value in the structure is ignored and is overwritten with the real number of frames in the file.

Arguments
in void *headerp This is a pointer to the MainAVIHeader being written.
Return Values
Success
Failure
FileNotOpen
StorageAllocationFailure
InvalidArgument

ReturnCode put_chunk(in void *v, in long size, in long fourcc, in long track, in long flags)

Description

This method inserts (writes) a chunk into the file at the current position. No byte-swapping is done on the data. The FOURCC value is edited to add the track number. For example, if the caller supplies 00wb as the FOURCC value and 1 as the track value, the RIFF chunk is created as 01wb. The flags value is ignored if the file does not have an index. The file header is updated to reflect the real number of frames written to the file. This method is not affected by the select_track and un_select_track methods.

Arguments
in void *v This is a pointer to the chunk data to be written.
in long size This is the size of the data.
in long fourcc This is the RIFF FOURCC value to be used for the new chunk.
in long track This is the track number for the new chunk.
in long flags This is the flags value that is placed in the dwFlags field of the index entry for this new chunk.
Return Values
Success
Failure
FileNotOpen
StorageAllocationFailure
InvalidTrack
InvalidArgument

ReturnCode put_stream_headers(in long count, in void *headerp)

Description

This method puts AVIStreamHeader stream headers into the file. This header can be rewritten at any time. The object gets better performance and uses less temporary space if the header is written before writing frames.

Arguments
in long count This is the number of AVIStreamHeader structures pointed to by headerp.
in void *headerp This points to count AVIStreamHeader structures that are to be written.
Return Values
Success
Failure
FileNotOpen
InvalidArgument
StorageAllocationFailure

ReturnCode put_strd_data (in long count, in long *sizep, in void *datap)

Description

This method puts strd chunks into the file.

Arguments
in long count This is the number of strd chunks.
in long *sizep This is a pointer to an array of count longs that give the sizes for the strd chunks.
in void *datap This points to an array of pointers to the data to be written as strd chunks.
Return Values
Success
Failure
FileNotOpen
InvalidArgument
StorageAllocationFailure

ReturnCode put_strf_data(in long count, in long *sizep, in void *datap)

Description

This method puts strf chunks into the file.

Arguments
in long count This is the number of strf chunks.
in long *sizep This is a pointer to an array of count longs that give the sizes for the strf chunks.
in void *datap This points to an array of pointers to the data to be written as strf chunks.
Return Values
Success
Failure
FileNotOpen
StorageAllocationFailure
InvalidArgument

ReturnCode seek_to_frame(in long frame_number)

Description

This function attempts to seek to the frame number specified as an argument. If unsuccessful, the file position is unmodified. Frame numbers start at 0. A file with 10 frames has frame numbers 0 to 9. If the file does not have an index, seek operations are still possible but with reduced performance. The object goes to frame 0 and steps through the frames until it reaches the target frame.

Arguments
in long frame_number This is the frame number desired.
Return Values
Success
Failure
InvalidArgument
FileNotOpen
RiffFailure

ReturnCode select_track(in long track)

Description

This function is used to select which tracks are returned by the get_*chunk functions. All tracks are selected by default when the file is opened. Multiple tracks can be selected by multiple use of this call. This method only applies when reading chunks from the file.

Arguments
in long track This is the number of the track to be selected. A -1 value means to select all tracks.
Return Values
Success
Failure
InvalidTrack
FileNotOpen
StorageAllocationFailure

ReturnCode status_ok()

Description

This function checks the status of the object. If the file is not open, this function returns an error.

Return Values
Success
Failure
FileNotOpen

ReturnCode un_select_track(in long track)

Description

This function is used to select which tracks are returned by the get_*chunk functions. All tracks are selected by default when the file is opened. Multiple tracks can be unselected by multiple use of this method. This method only applies when reading chunks from the file.

Arguments
in long track This is the number of the track to be unselected. A -1 value means to deselect all tracks.
Return Values
Success
Failure
InvalidTrack
FileNotOpen
StorageAllocationFailure

For introductory information, see Formatted File Access Objects.


[ Previous | Next | Contents | Glossary | Home | Search ]