[size="5"]Abstract
You have several options when working with AVI files.
- Parse the file yourself.
- Parse the file with MMIO routines.
- Piece together a DirectShow filter.
- Use the Win32 AVIFile API.
- Use MCI to draw it to a window.There are benefits and drawbacks to each of them, but only Microsoft's AVIFile api makes it easy enough for the novice, but advanced enough for most purposes. This document deals with the loading and interpreting of AVI files using the AVIFile interface. If you are already comfortable with DirectShow, then I recommend that method instead. As an alternative, AVIFile will allow you to process the many different kinds of AVI files, handle decompression, and read the video frames easily. The API is also for reading any Resource Interchange File Format (RIFF), so learning the API will enable you to process other types of RIFF files like WAV, and even help you to create your own custom format that extends AVI's capabilities while remaining compatible with other software.
This document will show you how to extract video and sound information from an AVI file. You'll see how to synchronize game elements over the top of the AVI video, and the sample code shows how the AVI can be blitted with transparency so it's superimposed over a game's action. You will receive royalty-free wrapper classes for avi files, bitmap files, and direct draw to get you started.
[size="5"]Introduction
When learning to process a file, I usually learn its file format and create a wrapper class to make it easier for the rest of my code. One thing noticed as files get more advanced, are that they're utilizing a chunk based format. WAV is probably the easiest of the chunk based, and PCM waves can be parsed with little difficulty. The reason why I recommend using an API for AVI files, though, is because they come in so many forms that you must either learn them all or limit your capability in some way. They're also usually compressed with one of several different formats.
This document is designed to lead you through the entire process from beginning to end. I only talk about the stuff that's pertinent to opening and getting frames and audio from the file. I don't go into how the sound can be played back or the images rendered, because there are many different ways depending on what you want to do. The sample code, written using MSVC++ 6.0, displays the frame sequence using DirectX 7.0 in full screen exclusive mode. If there's popular demand I will submit other articles to describe in more detail how the video is rendered and sound played back.
[size="5"]Reference
[size="3"]
Project Settings
You'll need to link to winmm.lib, and vfw32.lib to use the AVIFile functions. They should be included in Borland as well. They're included with MSVC++ 6.0, but should also be available for versions as low as 4.0. Newer versions of the libraries are also part of the latest Platform SDK release from Microsoft.
You can use these functions with any kind of project: C, C++, MFC, Win32, console app, Direct Draw, Direct3D, etc.
[size="3"] Initialization
[size="3"] Opening the AVI FileAviFileInit();
The AVIFileOpen function only takes a string for the filename, as opposed to a file handle. This means that you'll be unable to embed an AVI file into a proprietary WAD format and load it directly from within while using this API, unless you can figure out a trick. It's possible to encode the file format and/or change the extension to protect your copyright for a game's release.
[size="3"] Getting the File's InfoPAVIFILE pAviFile;
if(AVIFileOpen(&pAviFile, "filename.avi", OF_READ, NULL))
// error
The info structure contains some extra stuff you might use later on, but nothing spectacular or essential for our purpose so I won't go into that here.AVIFILEINFO info;
AVIFileInfo(pAviFile, &info, sizeof(info));
[size="3"] Finding Audio and Video Streams
An AVI file may have any number of streams of any type. Usually they're just audio and video streams. It's possible to open all of the streams and then query what type they are later. Usually a program ignores streams it doesn't recognize or need. This allows you to innovate the AVI file format, while retaining compatibility with other programs.
I'll use preallocated arrays to contain only the audio and video streams in the file. Ordinarily I would recommend a linked list, but such implementation details are out of this document's context, not to mention most AVI files will have only one audio and video stream anyway.
The loops to open each stream are pretty strait forward. I explicitly specify what type of stream to load, either streamtypeAUDIO or streamtypeVIDEO. I ignore any other stream that might be in the file, like streamtypeTEXT or streamtypeMIDI. To load any stream type available, specify zero for the streamtype.PAVISTREAM
pAudio[MAX_AUDIO_STREAMS],
pVideo[MAX_VIDEO_STREAMS];
int nNumAudioStreams=0, nNumVideoStreams=0;
Now we have neat arrays of audio and video streams, and we know the number contained in each. Processing them will consist of looping through these streams, so here forward I simply refer to the current stream as pStream. Note that we haven't actually loaded anything yet, we've merely obtained a handle to the data that's in the file. This allows us to play potentially massive AVI files without a significant memory impact.do {
if(AVIFileGetStream(pAviFile, &pAudio[nNumAudioStreams],
streamtypeAUDIO, nNumAudioStreams))
break;
} while(++nNumAudioStreams < MAX_AUDIO_STREAMS);
do {
if(AVIFileGetStream(pAviFile, &pVideo[nNumVideoStreams],
streamtypeVIDEO, nNumVideoStreams))
break;
} while(++nNumVideoStreams < MAX_VIDEO_STREAMS);
[size="3"] Getting a Stream's Info
A stream's information is obtained simply through the use of this function.
Like the file's info, this stuff isn't essential for processing an AVI file. There are some things you can calculate from the structure members, but I've found an easier way to determine these values that's described later.AVISTREAMINFO info;
if(AVIStreamInfo(pStream, &infoAudio, sizeof(info)))
// error
[size="3"] Determining a Stream's Format
Since a stream can be of numeral kinds, we need to know its format. First of all, we must know how long the format data is. The following code accomplishes that.
LONG lSize; // in bytes
if(AVIStreamReadFormat(pStream, AVIStreamStart(pStream), NULL, &lSize))
// error
Audio Stream Specifics[size="3"] Processing an Audio Stream
The format data for an audio stream is based on the WAVEFORMAT structure, but it may have a few extra data members at the end and a different structure name. You can tell what structure it is by comparing the lSize variable with the sizeof(WAVEFORMATEX) or sizeof(PCMWAVEFORMAT). These structures, and most others, simply extend WAVEFORMAT with a few extra bytes.
PCMWAVEFORMAT includes the important wBitsPerSample member, and WAVEFORMATEX includes both wBitsPerSample and cbSize. The cbSize member tells how many extra bytes are stored after the WAVEFORMATEX structure. The extra bytes are for non-Pulse Code Modulation (PCM) formats, if you want to support those. Usually you'll only find PCM formats, but the code you're about to see supports all of them.
We'll accomplish that by reading in a chunk and casting it to a WAVEFORMAT pointer.
Now that we know the audio format, we are better equipped to interpret the actual sound information in order to play it back. It's not necessary to be familiar with the structure members just yet.LPBYTE pChunk = new BYTE[lSize];
if(!pChunk)
// allocation error
if(AVIStreamReadFormat(pStream, AVIStreamStart(pStream), pChunk, &lSize))
// error
LPWAVEFORMAT pWaveFormat = (LPWAVEFORMAT)pChunk;
Video Stream Specifics
The BITMAPINFO structure defines the format for a video stream. That structure contains one of the BITMAPINFOHEADER, BITMAPV4HEADER, or BITMAPV5HEADER structures, followed by the palette information if the image format is 8bits per pixel. Software for Windows 98 or Windows2000 should write the BITMAPV5HEADER, but for reading an AVI file we need to determine which version was stored in the file in order to be backward compatible. That's easiest by allocating and reading it all in one chunk like we did with the sound format.
The reason why that's possible, is because each structure begins with the same information as BITMAPINFO, but adds a few extra members to the previous version. If you determine that you need these extra members for a project you're working on, it's easy to cast the data chunk over to the appropriate structure pointer:LPBYTE pChunk = new BYTE[lSize];
if(!pChunk)
// allocation error
if(AVIStreamReadFormat(pStream, AVIStreamStart(pStream), pChunk, lSize))
// error
The BITMAPINFO structure tells us a lot about the image format. It tells what type of compression is used, the frame size, bit depth, etc. That's all the necessary information one needs when converting image data over to a GDI HBITMAP, MFC CBitmap, LPDIRECTDRAWSURFACE, or custom format.// Only if you need to:
LPBITMAPINFO pInfo = (LPBITMAPINFO)pChunk;
DWORD biSize = pInfo->bmiHeader.biSize;
switch(biSize)
{
case sizeof(BITMAPV5HEADER):
// ...
case sizeof(BITMAPV4HEADER):
// ...
case sizeof(BITMAPINFOHEADER):
// ...
};
Streams of this type are typically uncompressed, so it's probably best to describe that method. We'll start by determining the size of the audio data contained in the stream.
Since we already know the stream's format, we'll load the sound data into a byte buffer.LONG lSize;
if(AVIStreamRead(pStream, 0, AVISTREAMREAD_CONVENIENT, NULL, 0, &lSize, NULL))
// error
So now with the sound format and data, it's a simple task to create a DirectSound buffer, play it back through a Win32 multimedia function, or custom library. Changing the function calls won't do anything special, but you can read about the parameters if you want in the online docs.LPBYTE pBuffer = new BYTE[lSize];
if(!pBuffer)
// error
if(AVIStreamRead(pStream, 0, AVISTREAMREAD_CONVENIENT, pBuffer, lSize, NULL, NULL))
// error
[size="3"] Processing a Video Stream
The great thing about AVIFile is that it handles decompression of video for us. We'll initialize that feature in the following code.
Since we determined what format the frames are stored in earlier, you can modify it slightly, or calculate a new format from scratch, and have AVIFile convert the frames into whatever format best suits your rendering system.
The PGETFRAME pointer is used by the system to handle the decompression of the video frames. The NULL parameter says I just want AVIFile to leave the image format the way it is. You can try passing a BITMAPINFO pointer, perhaps by changing the image format that was loaded before.
Now that the decompression system has been initialization, we can enter the loop that plucks and displays each frame for this video stream. AVIFile is organized so you only need one frame in memory at a time, allowing you to quickly play large files, but you can copy or buffer the frames as needed.PGETFRAME pgf;
pgf = AVIStreamGetFrameOpen(pStream, NULL);
if(!pgf)
// error
Next we'll determine which frame we need to pluck from the stream. Usually that's accomplished by incrementing the value lTime each millisecond via a multimedia timer, or calculating it via the difference in time between frame renderings. The API functions are then used to calculate a frame value based on the amount of time elapsed since the beginning of play. This allows accurate playback for whatever the file specifies as its playback speed, regardless of the time it takes us to render a frame. With this code you'll be able to synchronize the video with speech or game events. Alternatively you can calculate the lFrame variable through any means depending on what effect you're accomplishing.
With that information, it's easy to pluck a packed DIB from the video stream.// Precalculated: When stream is opened
lEndTime = AVIStreamEndTime(pStream);
// Calculated just before next frame is blitted
if(lTime <= lEndTime)
lFrame = AVIStreamTimeToSample(pStream, lTime);
else // the video is done
The packed DIB is comprised of a BITMAPINFOHEADER structure, followed by the palette information if needed, and then followed by the bitmap data. All of this is just one sequential block of memory, so it's possible to calculate the palette and bitmap pointers using pointer arithmetic.LPBITMAPINFOHEADER lpbi;
lpbi = (LPBITMAPINFOHEADER)AVIStreamGetFrame(pgf, lFrame);
The image data that has been extracted is only good until the next time we call AVIStreamGetFrame, so it's important to display it to screen, copy it to a texture or bmp file, or whatever you want to do with it. I don't go into such details here, but you'll see how in the provided sample code.// For 16, 24, or 32bit image formats
LPBYTE pData = lpbi + lpbi->biSize;
// For 8bit image formats
LPBYTE pData = lpbi + lpbi->biSize + 256 * sizeof(RGBQUAD);
When all of the frames have been processed, it's important to close down the decompression system as follows.
[size="3"] Cleaning upif(AVIStreamGetFrameClose(pgf))
// error
After you're done with the streams, and file, you release them as follows. That's all there is to it! Hopefully I have helped you to understand this file format. Feel free to email me if you have any questions.
[size="5"] [size="2"]// Remember to release all streams
AVIStreamRelease(pStream);
AVIStreamRelease(pStream);
AVIFileRelease(pAviFile);
AVIFileExit();
[size="5"]Conclusion
Did you skip the document just to get to the samples?
How can you have any pudding if you haven't finished your meat??[Visit my Web Site!!]ss
- Pink Floyd, "The Wall"
[size="3"] Sample One
The first sample plays an AVI file that was made by Klowner. This sample uses my CDirectDraw wrapper class to do the rendering. The file is first played forwards, and then played in reverse so the action is seamless. It's time synchronized so the visual frame rate is consistent with the frame rate specified by Klowner when he made the file. Each frame is also blitted with transparency, so the sequence can be superimposed over a backdrop during a game's action.
[size="3"] Sample Two, featuring the PowerRender API
The second sample shows a rotating teapot superimposed over the AVI file's action. It may look like the teapot is being stretched, skewed and zooming in and out, but I used PR's camera features namely field of view and aspect ratio to optimize those effects. This sample requires a hardware accelerator compatible with Microsoft's Direct3D in order to operate, but should be compatible with OpenGL, GLIDE, or software rendering depending on what you recompile it for. If you want more information on the professional PowerRender api, here's their site: Egerter software.
(C)1999 Jonathan Nix. All Rights Reserved.
All sample code is subject the most current copyrights and/or disclaimers posted on my website.
PowerRender is a trademark of Egerter Software.
Direct3D and Microsoft are trademarks of Microsoft Coorporation.
