Dali: Avi Library -- C API

Header Files

#include <dvmavi.h>

Type Definitions

AviFile

This structure maintains the internal state corresponding to an open avi file.

        typedef struct AviFile {
            PAVIFILE aviHandle;
            short  numStreams;
            int length;
            int flags;
        } AviFile;

aviHandle

handle returned by AVIFileOpen

numStreams

The Number of media streams

length

Number of frames in the AVI file

flags

VFW specified flags

AviStream

This structure maintains the internal state corresponding to a single open stream in an avi file. The data in this structure is common to both audio and video streams.

        typedef struct AviStream {
            PAVISTREAM streamHandle;  
            int type;
            int codec;
            int length;
            int start;
            int sofar;
            void *data;
        } AviStream;

streamHandle

Handle returned by AVIGetStream

type

Either AVISTREAM_AUDIO or AVISTREAM_VIDEO

codec

The fcc (not used for audio)

length

Number of frames in the stream for video. Number of blocks for audio.

start

sample number of the first frame

sofar

sample number of the next frame to decompress

data

format specified data (AviVIdeoStream or AviAudioStream

AviVideoStream

This structure maintans information relevant to open video streams.

        typedef struct AviVideoStream {
            PGETFRAME gf;              /* getframe handle for decompression */
            PAVISTREAM cs;             /* handle to compressed stream (for writes) */
            unsigned char *fb;         /* framebuffer (for writes) */
            short width;               /* width of each frame */
            short height;              /* height of each frame */
            short fps;                 /* frames per second .. */
            short keyinterval;         /* Interval between key frames */
        } AviVideoStream;

gf

getframe handle for decompression

cs

handle for compressed stream (for writes)

fb

framebuffer (for writes)

width

width of each frame

height

height of each frame

fps

number of frames per second

keyInterval

interval between key frames

Constants

Return Code

These represent the possible return values from Dali avi functions. DVM_AVI_OK is returned if all goes well. The error codes are included below. Apart from these, standard video for windows errors may also be returned. These typically bave a AVIERR_ prefix, and are defined in the windows header files.

    #define DVM_AVI_BAD_SIZE             1     /* ByteImage size does not match stream size */
    #define DVM_AVI_NOT_VIDEO            2     /* Not a video stream */
    #define DVM_AVI_GET_FRAME_FAILED     3     /* Call to AVIStreamGetFrame() failed */
    #define DVM_AVI_UNINITIALIZED        4     /* Stream not initialized */
    #define DVM_AVI_WRITE_FAILED         5     /* Call to AVIStreamWrite() failed */
    #define DVM_AVI_FILE_OPEN_FAILED     7     /* AVIFileOpen() failed */
    #define DVM_AVI_FILE_INFO_FAILED     8     /* AVIFileInfo() failed */
    #define DVM_AVI_BAD_STREAM_NUM      10     /* Requested to read non-existent stream */
    #define DVM_AVI_GETSTREAM_FAILED    11     /* AVIFileGetStream() failed */
    #define DVM_AVI_STREAM_INFO_FAILED  12     /* AVIStreamInfo() failed */
    #define DVM_AVI_READ_FORMAT_FAILED  13     /* AVIStreamReadFormat() failed */
    #define DVM_AVI_NOT_RGB             14     /* Video stream is not RGB */
    #define DVM_AVI_UNSUPPORTED_TYPE    15     /* Stream type is not supported */
    #define DVM_AVI_NO_DECOMPRESSOR     16     /* Decompressor not installed */

Operators

File

int AviFileOpen(char *filename, AviFile **aviFilePtr)

Opens an existing avi file filename for reading. Fills in the aviFilePtr with a ponter to a AviFile structure. Returns AVIERR_MEMORY if memory allocation fails. Can also return other Video For Windows errors. Use AviTranslateError() to get a textual description of the error.

int AviFileCreate(char *filename, AviFile **aviFilePtr)

Creates an avi file filename for writing. In case the file exists, it is truncated. Fills in the aviFilePtr with a ponter to a AviFile structure. Returns AVIERR_MEMORY if memory allocation fails. Can also return other Video For Windows errors. Use AviTranslateError() to get a textual description of the error.

int AviFileClose(AviFile *aviFile)

Closes the file and frees memory associated with handle aviFile

Stream

int AviStreamOpen(AviFile *aviFile, int streamnum, AviStream **strPtr)

Opens the streamnum -th stream in the avi file aviFile, where the first stream is numbered 0. This stream must already exist in the file aviFile. Fills in the strPtr with a ponter to a AviStream structure. Returns AVIERR_MEMORY if memory allocation fails. Returns DVM_AVI_BAD_STREAM_NUM if there is no stream with this ordinal. Returns DVM_AVI_NOT_RGB if the video bit depth is not 24. Can also return other Video For Windows errors. Use AviTranslateError() to get a textual description of the error.a textual description of the error.

int AviStreamClose(AviStream *aviStream)

Closes the stream and frees memory associated with handle aviStream

Video Stream

int AviVideoStreamCreate (AviFile *aviFile, int codec, int w, int h int keyinterval, int quality, int bitrate, AviStream **strPtr)

Create a video stream in the file aviFile, using codec. The frame width and height are given by w and h. The keyinterval specifies the number of frames between key frames, and is used by some codecs. quality is a number between 0 and 100, higher numbers indicating better desired quality. Finally, bitrate is the desired bit rate of the stream in bits per second. The codec value is exactly of the form video for windows expects, and can be obtained from the short textual form by calling a VFW macro. Fills in the strPtr with a ponter to a AviStream structure. Returns AVIERR_MEMORY if memory allocation fails. Can also return other Video For Windows errors. Use AviTranslateError() to get a textual description of the error.

int AviStreamStartDecode(AviStream *strPtr)

This should be called prior to calling any functions to decode any frames. Returns AVIERR_NOCOMPRESSOR if no suitable compressor could be found to decode this stream

int AviStreamStopDecode(AviStream *strPtr)

This should be called after decoding frames in the stream is complete Frees up memory allocated by AviStreamStartDecode

int AviVideoFrameRead(AviStream *strPtr, ByteImage *r, ByteImage *g, ByteImage *b)

Decodes the next video frame in the stream and fills in the ByteImages r, g, b with its contents. Returns DVM_AVI_NOT_VIDEO if strPtr is not a video stream. Returns DVM_AVI_BAD_SIZE if the ByteImage size does not match the width and height in the stream header. Returns DVM_AVI_GET_FRAME_FAILED if video for windows did not manage to decode the frame.

int AviVideoFrameWrite(AviStream *strPtr, ByteImage *r, ByteImage *g, ByteImage *b)

Encodes the next frame given in the ByteImages r, g, b and writes them out to the stream. Returns DVM_AVI_NOT_VIDEO if strPtr is not a video stream. Returns DVM_AVI_BAD_SIZE if the ByteImage size does not match the width and height in the stream header. Can also return other Video For Windows errors. Use AviTranslateError() to get a textual description of the error.a textual description of the error.

int AviVideoFrameSeek(AviStream *strPtr, int frameno)

Seeks to the frame position given by frameno. Also returns this frame position.

int AviVideoFrameTell(AviStream *strPtr)

Returns the current frame position in the stream.

int AviVideoFrameSkip(AviStream *strPtr)

Skips the next frame position in the stream.

int AviVideoFrameRewind(AviStream *strPtr)

Sets the frame position to the beginning of the stream.

AviStreamGetType(AviStream *aviStream) AviStreamGetCodec(AviStream *aviStream) AviStreamGetLength(AviStream *aviStream) AviStreamGetWidth(AviStream *aviStream) AviStreamGetHeight(AviStream *aviStream) AviStreamGetFps(AviStream *aviStream)

These functions (macros in the tcl version) get the corresponding fields from the AviStream and AviVideoStream structure.